Skip to main content
Version: 1.0

Two Order API

Download this API's OpenAPI YAML

This API is for creating orders connected to an online purchase through your solution. The API also functions as a central building block when using other Two APIs, e.g. Marketplace API, and Trade Account Onboarding API.

Specifically, the API enables you to:

  • Check whether a buyer is accepted for credit before placing the order (Order intent)
  • Create orders
  • Fulfil orders (Send invoice from Two)
  • Edit orders
  • Cancel orders
  • Refund orders (Send credit note)
  • Download invoice

Below you will find a description of a typical flow of how the different endpoints are called. However, you might want to deviate from this order depending on your setup.

Step 0: Use the Two Company Search API to find the company​

By using the Two Company Search API, you ensure that the user places an order on behalf of the correct organization. It enables an improved user experience and lowers the friction.

Using Canonical IDs (Recommended): The Company Search API returns a canonical_id for each company. You can use this canonical_id when creating orders and order intents instead of providing full company details. This ensures data accuracy and simplifies integration.

Example:

{
  "buyer": {
    "company": {
      "company_canonical_id": "abc123def456"
    },
    "representative": { ... }
  }
}

Step 1: Check whether a buyer will be accepted for credit during checkout (Order intent)​

Use POST /v1/order_intent to credit check your buyers during the checkout. Only enable Two as the payment option if the credit check is approved. Collect the tracking_id from the response of the order intent in order to connect the order_intent with the actual order being placed by the buyer.

Step 2: Create order​

Create an order by building a request body containing all required elements and call the POST /v1/order endpoint.

  1. Read the state and status of the order response.
  2. Check if the status is APPROVED.
  3. Check if the state is UNVERIFIED, and redirect the user to the payment_url.

After completing the verfication, the user is redirected back to your order confirmation page.

Step 3: Confirm order​

On the order confirmation page use the POST /v1/order/<order_id>/confirm endpoint to confirm that the user has arrived at the order confirmation page.

Step 4: Handling orders​

Cancel order​

Use POST /v1/order/<order_id>/cancel to cancel a specific order.

Edit order​

Use PUT /v1/order/<order_id> with a specified request body to edit an order.

Fulfil order​

Use POST /v1/order/<order_id>/fulfilled with a specified request body to fulfil all line items of an order.

Note: Include a request body in order to do a partial fulfillment.

Refund order​

Use POST /v1/order/<order_id>/refund to refund a specific order.

Note: Include a request body in order to do a partial refund.

Environments​

Testing​

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production​

https://api.two.inc

Authentication​

For instructions on how to obtain API keys, visit this page. You will obtain two different keys, an initial one for testing in our sandbox environment and once ready, for production. Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe. Your API key is not to be shared with anyone, including in your version control system, client-side code, in public chatrooms and so on. The API key is applied in the request header. For example:

GET /something
X-Api-Key: secret_test_aabbccddeeff0123456789

API Keys have the following structure: secret_<env>_<key> where:

  • env is determined by the environment (prod for production, test for test environments)
  • key is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.

Security Scheme Type:

apiKey

Header parameter name:

X-Api-Key