Two Order API (1.0)

Download OpenAPI specification:Download

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. For inspiration you can find a sample implementation of Two at https://demo.two.inc

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

By using the Two 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.

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

Company

Lookup company address

Request
path Parameters
company_id
required
string

ID of the company

country_code
required
string

Country code e.g NO, GB, SE

Responses
200

Company address

default

Error response

get/v1/{country_code}/company/{company_id}/address
Request samples 
Response samples 
application/json
{
  • "address": {
    }
}
Order intent
Create order intent
The endpoint enables the merchant to check in advance whether invoice payment is applicable as a payment method for the Buyer. Two will perform a risk assessment and credit check using the data provided in the OrderIntent before a boolean is returned as a result. If line_items are provided Two will be able to do a more accurate assessment and the approval rate will in general increase.


Request 
Request Body schema: application/json
required
object (Buyer) 
Fields representing the buyer. Some elements are optional. Providing optional information enables a more accurate evaluation of the buyer.


 
currency
required
string (Currency) 
Currency code in ISO 4217 format. E.g. 'NOK'


 
gross_amount
required
string <decimal>  (Gross Amount) ^-?[0-9]+(\.[0-9]{0,2})?
net_amount + tax_amount


 
invoice_type
string (InvoiceTypeEnum) 
FUNDED_INVOICE: Two will handle the invoice and transfer the funds to the merchant as per the factoring agreement. The invoice_details field will be populated by Two. DIRECT_INVOICE: Two generates and sends the invoice to the customer based on the bank account provided by the merchant, but the merchant takes the full credit and fraud risk on direct invoices and they will not receive a payout.


 Enum: "FUNDED_INVOICE" "DIRECT_INVOICE" "CARD"  
required
Array of objects (Line Items) 
List of the line items that constitute the order.


 
merchant_id
string <uuid>  (Merchant Id) 
A globally unique merchant ID set by Two.


 
merchant_short_name
string (Merchant Short Name) 
 Deprecated 
Deprecated. Use merchant_id where possible.


 
order_origination
string (OrderOriginationEnum) 
IN_STORE orders are not enabled by default. Please reach out to us if you would like to discuss IN_STORE orders.


 Enum: "ONLINE" "IN_STORE"  
object (Shipping Address) 
Order shipping address. Optional. Providing this information enables a more accurate evaluation of the buyer.


 
Responses 
201
Create order intent


default
Error response


post/v1/order_intent
Request samples 
application/json
{
  • "merchant_id": "32d8eb3f-8ac3-4aca-82b9-dbbd6f416cfb",
  • "gross_amount": "120",
  • "currency": "GBP",
  • "order_origination": "ONLINE",
  • "buyer": {
    },
  • "line_items": [
    ]
}
Response samples 
application/json
{
  • "approved": true,
  • "buyer": {
    },
  • "currency": "GBP",
  • "decline_reason": null,
  • "gross_amount": "120.00",
  • "id": "5af5a991-8822-4b61-b892-2ffdd2931fba",
  • "invoice_type": "FUNDED_INVOICE",
  • "line_items": [
    ],
  • "merchant_id": "32d8eb3f-8ac3-4aca-82b9-dbbd6f416cfb",
  • "merchant_short_name": "tillittestuk",
  • "order_origination": "ONLINE",
  • "tracking_id": "3987eb99-f726-436a-aed1-1c77a1ceb667"
}
Get order intent
The endpoint fetches a specific order intent.


SecurityX-Api-Key 
Request 
path Parameters
order_intent_id
required
string
 
Responses 
200
Get order intent


default
Error response


get/v1/order_intent/{order_intent_id}
Request samples 
Response samples 
application/json
{
  • "approved": true,
  • "buyer": {
    },
  • "currency": "GBP",
  • "decline_reason": null,
  • "gross_amount": "120.00",
  • "id": "5af5a991-8822-4b61-b892-2ffdd2931fba",
  • "invoice_type": "FUNDED_INVOICE",
  • "line_items": [
    ],
  • "merchant_id": "32d8eb3f-8ac3-4aca-82b9-dbbd6f416cfb",
  • "merchant_short_name": "tillittestuk",
  • "order_origination": "ONLINE",
  • "tracking_id": "3987eb99-f726-436a-aed1-1c77a1ceb667"
}
Order
Create order
Endpoint to create a new order in Two's system. Once all the required order data has been added to the request body and the order has been created successfully, Two performs a credit check of the customer and updates the status. In adition to general information about the order and its content, the response body contains the status of the credit check and payment_url which is used for customer identification. After the verification step is completed successfully, the order will change state. The order is now approved and verified, i.e. the order is placed. Later, the order has to be handled by the merchant, either through Two's API enpoints or the merchant portal. Note: When creating an order it is important to note that the invoice_type, country_prefix, and organization_number has to match what the merchant has signed up for with Two.


SecurityX-Api-Key 
Request 
Request Body schema: application/json
billing_account_id
string <uuid>  (Billing Account Id) 
ID for the billing account attached to the order created through the Two Billing Account API.


 
required
object (Billing Address) 
Order billing address


 
required
object (Buyer) 
Fields representing the buyer


 
buyer_department
string (Buyer Department) 
Department the purchase is to be registered on


 
buyer_project
string (Buyer Project) 
Project the purchase is to be registered on


 
buyer_purchase_order_number
string (Buyer Purchase Order Number) 
Purchase order number to attribute to the order


 
buyer_reference
string (Buyer Reference)   <= 140 characters 
General buyer reference field for information that is not covered by the specific reference fields, e.g. PO-number. Note: Maximum 140 characters


 
currency
required
string (CurrencyEnum) 
Currency code in ISO 4217 format. E.g. 'NOK'


 Enum: "NOK" "SEK" "GBP" "EUR" "USD" "DKK" "CHF" "RON" "PLN" "CZK"  
discount_amount
string <decimal>  (Discount Amount) ^-?[0-9]+(\.[0-9]{0,2})?
 Default:  0
Discount amount if discount is set on the invoice/order level, excluded tax


 
discount_rate
string <decimal>  (Discount Rate) ^-?[0-9]+(\.[0-9]{0,6})?
 Default:  0
Discount rate if discount is set on the invoice/order level


 
object (Electronic Invoice Recipient) 
electronic_invoice_recipient


 
gross_amount
required
string <decimal>  (Gross Amount) ^-?[0-9]+(\.[0-9]{0,2})?
net_amount + tax_amount


 
object (Invoice Details) 
Invoice details are provided by the merchant via Merchant Portal when invoice_type is DIRECT_INVOICE, Two Bank or a 3rd-party bank when invoice_type is FUNDED_INVOICE and empty when invoice_type is CARD.


 
required
Array of objects (Line Items) 
List of the line items that constitute the order


 
merchant_additional_info
string (Merchant Additional Info) 
Additional info the merchant can connect to the order


 
merchant_id
string <uuid>  (Merchant Id) 
A globally unique merchant ID set by Two.


 
merchant_order_id
required
string (Merchant Order Id) 
Your order ID to register against the order


 
merchant_payout_account_alias
string (Merchant Payout Account Alias) 
Optional payee account alias account identifier for multiple accounts setup.


 
merchant_reference
string (Merchant Reference) 
Field set by merchant for adding a reference to be used internally by the merchant. Does not appear on invoice.


 
merchant_short_name
string (Merchant Short Name) 
 Deprecated 
Deprecated. Use merchant_id where possible.


 
object (Merchant Urls) 
List of urls hosted by the merchant.


 
merchant_user_id
string (Merchant User Id)   non-empty 
Your internal ID of the user (the employee of your business customer) registered for one-click purchase through the Two Trade Account Onboarding API.


 
net_amount
required
string <decimal>  (Net Amount) ^-?[0-9]+(\.[0-9]{0,2})?
(quantity * unit_price) - discount_amount


 
order_note
string (Order Note) 
General note/message from the buyer to the merchant


 
order_origination
string (OrderOriginationEnum) 
IN_STORE orders are not enabled by default. Please reach out to us if you would like to discuss IN_STORE orders.


 Enum: "ONLINE" "IN_STORE"  
order_placed_date
string <date-time>  (Order Placed Date) 
Date order was placed (UTC)


 
order_type
string (OrderTypeEnum) 
Type of order (Buyer or Merchant initiated)


 Enum: "BUYER_INITIATED" "MERCHANT_INITIATED"  
recurring
boolean (Recurring) 
If set to true, an invoice will be generated periodically according to the specification provided in recurring_details


 
object (Recurring Details) 
Currently not available


 
sale_country_code
string (Sale Country Code) 
Optional sale country code (ISO 3166 Alpha-2) to use for this order, if null defaults to buyer country code.


 
required
object (Shipping Address) 
Order shipping address


 
object (Shipping Details) 
Optional shipping details to track the shipment


 
tax_amount
required
string <decimal>  (Tax Amount) ^-?[0-9]+(\.[0-9]{0,2})?
net_amount * tax_rate


 
Array of objects (Tax Subtotals) 
Tax Subtotals: only used for PEPPOL compliant orders


 
tracking_id
string (Tracking Id) 
Tracking ID from POST /order_intent


 
vendor_id
string (Vendor Id) 
Optional vendor ID for your reference


 
vendor_name
string (Vendor Name)   non-empty 
Optioanl vendor name for your reference


 
Responses 
201
Order created


default
Error response


post/v1/order
Request samples 
application/json
{
  • "gross_amount": "120.00",
  • "net_amount": "100.00",
  • "currency": "GBP",
  • "discount_amount": "0",
  • "discount_rate": "0",
  • "tax_amount": "20.00",
  • "buyer": {
    },
  • "order_intent_id": "ORDER_INTENT_TRACKING_ID",
  • "merchant_additional_info": "Additional line item information",
  • "merchant_order_id": "YOUR_MERCHANT_ORDER_ID",
  • "merchant_reference": "YOUR_MERCHANT_REFERENCE",
  • "merchant_urls": {
    },
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "shipping_details": {
    },
  • "line_items": [
    ]
}
Response samples 
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": null,
  • "credit_note_url": null,
  • "currency": "GBP",
  • "date_created": "2024-01-01 14:02:02.002222",
  • "date_fulfilled": null,
  • "date_updated": "2024-01-01 14:02:02.002222",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "elapsed_time_ms": null,
  • "electronic_invoice_recipient": null,
  • "event_log_url": "https://tillit.ai",
  • "external_order_id": null,
  • "external_order_status": null,
  • "fixed_fee": null,
  • "gross_amount": "120.00",
  • "id": "f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "invoice_details": {
    },
  • "invoice_insurance_provider": "NO_INSURANCE",
  • "invoice_type": "FUNDED_INVOICE",
  • "invoice_url": null,
  • "line_items": [
    ],
  • "merchant_additional_info": "Additional line item information",
  • "merchant_id": "1115e2ea-f6d2-4129-930f-3657600555ba",
  • "merchant_order_id": "YOUR_MERCHANT_ORDER_ID",
  • "merchant_payout_account_alias": null,
  • "merchant_reference": "YOUR_MERCHANT_REFERENCE",
  • "merchant_short_name": "tillit",
  • "merchant_urls": {
    },
  • "net_amount": "100.00",
  • "order_note": null,
  • "order_origination": "ONLINE",
  • "order_placed_date": "2024-01-01 14:02:02.002222",
  • "order_revision": null,
  • "order_type": "BUYER_INITIATED",
  • "original_order_id": null,
  • "parent_order_id": null,
  • "payment_url": "http://localhost:5000/order/f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "root_order_id": null,
  • "sale_country_code": null,
  • "shipping_address": {
    },
  • "shipping_details": {
    },
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "20.00",
  • "tax_subtotals": null,
  • "total_fee": null,
  • "tracking_id": null,
  • "vendor_id": null,
  • "vendor_name": null
}
Get order details
Endpoint to retrieve details related to a previously created order. The endpoint is typically used to check that the order has been verified successfully, in addition to other relevant state and status changes.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be retrieved


 
Responses 
200
OK


default
Error response


get/v1/order/{order_id}
Request samples 
Response samples 
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": null,
  • "credit_note_url": null,
  • "currency": "GBP",
  • "date_created": "2024-01-01 14:02:02.002222",
  • "date_fulfilled": null,
  • "date_updated": "2024-01-01 14:02:02.002222",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "elapsed_time_ms": null,
  • "electronic_invoice_recipient": null,
  • "event_log_url": "https://tillit.ai",
  • "external_order_id": null,
  • "external_order_status": null,
  • "fixed_fee": null,
  • "gross_amount": "120.00",
  • "id": "f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "invoice_details": {
    },
  • "invoice_insurance_provider": "NO_INSURANCE",
  • "invoice_type": "FUNDED_INVOICE",
  • "invoice_url": null,
  • "line_items": [
    ],
  • "merchant_additional_info": "Additional line item information",
  • "merchant_id": "1115e2ea-f6d2-4129-930f-3657600555ba",
  • "merchant_order_id": "YOUR_MERCHANT_ORDER_ID",
  • "merchant_payout_account_alias": null,
  • "merchant_reference": "YOUR_MERCHANT_REFERENCE",
  • "merchant_short_name": "tillit",
  • "merchant_urls": {
    },
  • "net_amount": "100.00",
  • "order_note": null,
  • "order_origination": "ONLINE",
  • "order_placed_date": "2024-01-01 14:02:02.002222",
  • "order_revision": null,
  • "order_type": "BUYER_INITIATED",
  • "original_order_id": null,
  • "parent_order_id": null,
  • "payment_url": "http://localhost:5000/order/f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "root_order_id": null,
  • "sale_country_code": null,
  • "shipping_address": {
    },
  • "shipping_details": {
    },
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "20.00",
  • "tax_subtotals": null,
  • "total_fee": null,
  • "tracking_id": null,
  • "vendor_id": null,
  • "vendor_name": null
}
Edit order
Endpoint to edit a previously created order which has not been fulfilled. The request body may contain changes related items, quantity, prices, etc.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be edited


 
Request Body schema: application/json
required
object (Billing Address) 
Order billing address


 
buyer_department
string (Buyer Department) 
The department the purchase is to be registered on


 
buyer_project
string (Buyer Project) 
The project the purchase is to be registered on


 
buyer_purchase_order_number
string (Buyer Purchase Order Number) 
The purchase order number the purchase should to be registered on


 
buyer_reference
string (Buyer Reference)   <= 140 characters 
General buyer reference field for information that is not covered by the specific reference fields, e.g. PO-number. Note: Maximum 140 characters


 
currency
required
string (CurrencyEnum) 
Currency code in ISO 4217 format. E.g. 'NOK'


 Enum: "NOK" "SEK" "GBP" "EUR" "USD" "DKK" "CHF" "RON" "PLN" "CZK"  
discount_amount
string <decimal>  (Discount Amount) ^-?[0-9]+(\.[0-9]{0,2})?
Discount amount if discount is set on the invoice level


 
discount_rate
string <decimal>  (Discount Rate) ^-?[0-9]+(\.[0-9]{0,6})?
Discount rate if discount is set on the invoice level


 
gross_amount
required
string <decimal>  (Gross Amount) ^-?[0-9]+(\.[0-9]{0,2})?
net_amount + tax_amount


 
object (Invoice Details) 
Invoice details are provided by the merchant via Merchant Portal when invoice_type is DIRECT_INVOICE, Two Bank or a 3rd-party bank when invoice_type is FUNDED_INVOICE and empty when invoice_type is CARD. Only editable for FUNDED_INVOICE orders if the order is in UNVERIFIED state.


 
required
Array of objects (Line Items) 
List of the line items that constitute the order


 
merchant_additional_info
string (Merchant Additional Info) 
Additional info the merchant can connect to the order


 
merchant_order_id
string (Merchant Order Id) 
Your order ID registered in your solution


 
merchant_reference
string (Merchant Reference) 
Field set by merchant for adding a reference to be used internally by the merchant. Does not appear on invoice.


 
net_amount
required
string <decimal>  (Net Amount) ^-?[0-9]+(\.[0-9]{0,2})?
(quantity * unit_price) - discount_amount


 
order_note
string (Order Note) 
General note/message from the buyer to the merchant


 
recurring
boolean (Recurring) 
If set to true, an invoice will be generated periodically according to the specification provided in recurring_details


 
object (Recurring Details) 
Currently not available


 
required
object (Shipping Address) 
Order shipping address


 
object (Shipping Details) 
Optional shipping details to track the shipment


 
tax_amount
required
string <decimal>  (Tax Amount) ^-?[0-9]+(\.[0-9]{0,2})?
net_amount * tax_rate


 
Array of objects (Tax Subtotals) 
'Tax Subtotals: only used for PEPPOL compliant orders'


 
Responses 
200
OK


default
Error response


put/v1/order/{order_id}
Request samples 
application/json
{
  • "gross_amount": "100",
  • "net_amount": "100",
  • "currency": "GBP",
  • "discount_amount": "0",
  • "discount_rate": "0",
  • "tax_amount": "0",
  • "invoice_details": {
    },
  • "recurring": false,
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": "string",
  • "line_items": [
    ],
  • "merchant_order_id": "02f98015-3309-48a3-8ded-ffc4285d06d0",
  • "merchant_reference": "Example reference",
  • "merchant_additional_info": "Example additional info",
  • "recurring_details": null,
  • "shipping_details": {},
  • "order_note": "Example note",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "tax_subtotals": null
}
Response samples 
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": null,
  • "credit_note_url": null,
  • "currency": "GBP",
  • "date_created": "2024-01-01 14:02:02.002222",
  • "date_fulfilled": null,
  • "date_updated": "2024-01-01 14:02:02.002222",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "elapsed_time_ms": null,
  • "electronic_invoice_recipient": null,
  • "event_log_url": "https://tillit.ai",
  • "external_order_id": null,
  • "external_order_status": null,
  • "fixed_fee": null,
  • "gross_amount": "120.00",
  • "id": "f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "invoice_details": {
    },
  • "invoice_insurance_provider": "NO_INSURANCE",
  • "invoice_type": "FUNDED_INVOICE",
  • "invoice_url": null,
  • "line_items": [
    ],
  • "merchant_additional_info": "Additional line item information",
  • "merchant_id": "1115e2ea-f6d2-4129-930f-3657600555ba",
  • "merchant_order_id": "YOUR_MERCHANT_ORDER_ID",
  • "merchant_payout_account_alias": null,
  • "merchant_reference": "YOUR_MERCHANT_REFERENCE",
  • "merchant_short_name": "tillit",
  • "merchant_urls": {
    },
  • "net_amount": "100.00",
  • "order_note": null,
  • "order_origination": "ONLINE",
  • "order_placed_date": "2024-01-01 14:02:02.002222",
  • "order_revision": null,
  • "order_type": "BUYER_INITIATED",
  • "original_order_id": null,
  • "parent_order_id": null,
  • "payment_url": "http://localhost:5000/order/f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "root_order_id": null,
  • "sale_country_code": null,
  • "shipping_address": {
    },
  • "shipping_details": {
    },
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "20.00",
  • "tax_subtotals": null,
  • "total_fee": null,
  • "tracking_id": null,
  • "vendor_id": null,
  • "vendor_name": null
}
Confirm order
SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be confirmed


 
Responses 
200
OK


default
Error response


post/v1/order/{order_id}/confirm
Request samples 
Response samples 
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": null,
  • "credit_note_url": null,
  • "currency": "GBP",
  • "date_created": "2024-01-01 14:02:02.002222",
  • "date_fulfilled": null,
  • "date_updated": "2024-01-01 14:02:02.002222",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "elapsed_time_ms": null,
  • "electronic_invoice_recipient": null,
  • "event_log_url": "https://tillit.ai",
  • "external_order_id": null,
  • "external_order_status": null,
  • "fixed_fee": null,
  • "gross_amount": "120.00",
  • "id": "f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "invoice_details": {
    },
  • "invoice_insurance_provider": "NO_INSURANCE",
  • "invoice_type": "FUNDED_INVOICE",
  • "invoice_url": null,
  • "line_items": [
    ],
  • "merchant_additional_info": "Additional line item information",
  • "merchant_id": "1115e2ea-f6d2-4129-930f-3657600555ba",
  • "merchant_order_id": "YOUR_MERCHANT_ORDER_ID",
  • "merchant_payout_account_alias": null,
  • "merchant_reference": "YOUR_MERCHANT_REFERENCE",
  • "merchant_short_name": "tillit",
  • "merchant_urls": {
    },
  • "net_amount": "100.00",
  • "order_note": null,
  • "order_origination": "ONLINE",
  • "order_placed_date": "2024-01-01 14:02:02.002222",
  • "order_revision": null,
  • "order_type": "BUYER_INITIATED",
  • "original_order_id": null,
  • "parent_order_id": null,
  • "payment_url": "http://localhost:5000/order/f36cfe22-5a46-4830-a8fa-0f2d7236e269",
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "root_order_id": null,
  • "sale_country_code": null,
  • "shipping_address": {
    },
  • "shipping_details": {
    },
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "20.00",
  • "tax_subtotals": null,
  • "total_fee": null,
  • "tracking_id": null,
  • "vendor_id": null,
  • "vendor_name": null
}
Renew order
Re-run credit check to renew our credit guarantee. If an external funding provider owns the order, we cancel that external order, re-create it, and update order.external_order_id on our internal order. Note that Norwegian Orders funded by Kredinor that have already been partially fulfilled cannot be renewed via our credit renewal end point.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be renewed


 
Responses 
200
OK


201
Accepted. Order has already been renewed


400
Bad Request


default
Error response


post/v1/order/{order_id}/renew
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Cancel order
Endpoint to change the state of an order to cancelled, and void the invoice. An order cannot change state to cancelled after being fulfilled. After fulfilment the merchant will have to refund the order instead.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be cancelled


 
Responses 
200
OK


default
Error response


post/v1/order/{order_id}/cancel
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Get fulfilled orders
This endpoint is used to fetch the associated fulfilled orders and refunds for a given order ID. If the requested order is linked to a partially fulfilled order, the endpoint returns all associated fulfilled orders.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the root order


 
Responses 
200
OK


default
Error response


get/v1/order/{order_id}/fulfillments
Request samples 
Response samples 
application/json
{
  • "fulfilled_orders": [
    ],
  • "refunds": [
    ]
}
Fulfil order
Endpoint to fully or partially fulfill an order based on the line item selection and gross, net amount values. If fully fulfilled, the endpoint changes the state of an order to FULFILLED. If partial fulfilment, the endpoint changes the status of an order to PARTIAL and creates a child order with 'FULFILLED' state. Note that fulfilment is an async process may take a few minutes to realise.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be partially fulfilled


 
Request Body schema: application/json
optional
invoice_issue_date
string <date>  (Invoice Issue Date) 
 
invoice_number
string (Invoice Number) 
Invoice number to be used for invoice if merchant is set up to provide own invoice numbers by Two. If not, then we will generate an auto-incremented one for you. Note this can not be set for orders in Norway.


 
object (Partial) 
The partially fulfilled order


 
Responses 
200
OK


default
Error response


post/v1/order/{order_id}/fulfillments
Request samples 
application/json
{
  • "invoice_issue_date": "2019-08-24",
  • "invoice_number": "string",
  • "partial": {
    }
}
Response samples 
application/json
{
  • "fulfilled_order": {
    },
  • "remained_order": {
    },
  • "elapsed_time_ms": { }
}
Complete partial order by cancelling
This end point will cancel any unfulfilled parts of the original root order, and in doing so will complete the order.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The root ID of the partial order to be completed/cancelled


 
Responses 
200
OK


default
Error response


post/v1/order/{order_id}/fulfillments/complete_partial
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Fulfil order (deprecated)Deprecated
Endpoint to change the state of the order (similar to "capture" for card payment). The invoice will be issued and distributed to the customer. The endpoint changes the state of a specified order to FULFILLED.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be marked as fulfilled


 
Request Body schema: application/json
optional
invoice_number
string (Invoice Number) 
Invoice number to be used for invoice if merchant is set up to provide own invoice numbers by Two. If not, then we will generate an auto-incremented one for you. Note this can not be set for orders in Norway.


 
Responses 
200
OK


default
Error response


post/v1/order/{order_id}/fulfilled
Request samples 
application/json
{
  • "invoice_number": "string"
}
Response samples 
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "buyer_purchase_order_number": null,
  • "buyer_reference": null,
  • "credit_note_url": null,
  • "currency": "GBP",
  • "date_created": "2024-01-01 14:02:02.002222",
  • "date_fulfilled": "2024-01-01 14:02:02.002222",
  • "date_updated": "2024-01-01 14:02:02.002222",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "elapsed_time_ms": null,
  • "electronic_invoice_recipient": null,
  • "event_log_url": "https://tillit.ai",
  • "external_order_id": null,
  • "external_order_status": null,
  • "fixed_fee": "0.00",
  • "fulfilled_order": null,
  • "gross_amount": "432.00",
  • "id": "03c90e8b-9089-44fd-9c66-656620cbc2c2",
  • "invoice_details": {
    },
  • "invoice_insurance_provider": "NO_INSURANCE",
  • "invoice_type": "FUNDED_INVOICE",
  • "invoice_url": "https://api.sandbox.two.inc/v1/invoice/03c90e8b-9089-44fd-9c66-656620cbc2c2/pdf?lang=en_US&v=original",
  • "line_items": [
    ],
  • "merchant_additional_info": null,
  • "merchant_id": "32d8eb3f-8ac3-4aca-82b9-dbbd6f416cfb",
  • "merchant_order_id": "32d8eb3f-8ac3-4aca-82b9-dbbd6f416cfb",
  • "merchant_payout_account_alias": null,
  • "merchant_reference": null,
  • "merchant_short_name": "tillittestuk",
  • "merchant_urls": {
    },
  • "net_amount": "360.00",
  • "order_note": null,
  • "order_origination": "ONLINE",
  • "order_placed_date": "2024-01-01 14:02:02.002222",
  • "order_revision": null,
  • "order_type": "BUYER_INITIATED",
  • "original_order_id": null,
  • "other_partial_orders": null,
  • "parent_order_id": null,
  • "payment_url": "https://sandbox.checkout.two.inc/order/03c90e8b-9089-44fd-9c66-656620cbc2c2",
  • "percentage_fee": "0.000000",
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "remained_order": null,
  • "root_order_id": null,
  • "sale_country_code": null,
  • "shipping_address": {
    },
  • "shipping_details": null,
  • "state": "FULFILLED",
  • "status": "APPROVED",
  • "tax_amount": "72.00",
  • "tax_subtotals": null,
  • "total_fee": "0.00",
  • "tracking_id": null,
  • "vendor_id": null,
  • "vendor_name": null
}
Get list of orders
Additionally following query params can be specified to manage pagination settings     limit - set limit items per page (default=100)     page - page number (calculated from limit and total results) to display     offset - items offset - alternative to page (pages not calculated if this param provided) Returns 401 error code if not authenticated. Returns 404 error code if merchant is not specified.


SecurityX-Api-Key 
Request 
query Parameters
end_date
string (End Date) 
Last date that should be included in the list of orders.


 
limit
integer (Limit) 
Limit the number of results per page to this number.


 
offset
integer (Offset) 
Number of offset results by (page parameter is disregarded if provided).


 
page
integer (Page) 
Page number to display results for.


 
start_date
string (Start Date) 
First date that should be included in the list of orders.


 
Responses 
200
OK


default
Error response


get/v2/orders
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": {
    }
}
Get order verification data
Endpoint to retrieve verification data related to an order. This endpoint is typically used by merchants to get data related to the verification links sent for an order.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order to be retrieved


 
Responses 
200
OK


default
Error response


get/v1/order/{order_id}/verification_data
Request samples 
Response samples 
application/json
{
  • "link_sent": true,
  • "link_recipient_phone_number": "+46XXXXXXXXXX",
  • "link_timestamp": "2024-01-01 14:02:02.002222",
  • "link_verification_successful": true
}
Send order verification notification to buyer
Within the notification, the buyer will receive a link that they need to visit to complete their order verification. Note that the order verification call only works for orders placed by valid trade account customers, and at this time, only SMS is supported.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
 
Request Body schema: application/json
channel
required
string (NotificationChannel) 
An enumeration.


 Enum: "sms" "email"  
Responses 
200
Trigger order verification notification to buyer


default
Error response


post/v1/order/{order_id}/notify
Request samples 
application/json
{
  • "channel": "sms"
}
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Refund order
Endpoint to refund an order. The customer will receive a credit note with a description of the items that are credited. An order can also be partially refunded by specifying the exact items and amount that are refunded in the JSON request body.


Request 
path Parameters
order_id
required
string
The ID of the order to be refunded


 
header Parameters
Idempotency-Key
string (Idempotency-Key)   <= 100 characters 
 
Request Body schema: application/json
Any of:
Fully or partially refund an order that has been fulfilled


amount
null (Amount) 
Gross amount being refunded


 
Array of objects (Buyer Refund Surcharges) 
 
currency
null (Currency) 
Currency refund is being issued in


 
order_revision
string <uuid>  (Order Revision) 
 
reason
string (Reason) 
Reason for order refund


 
refund_reference
string (Refund Reference)   non-empty 
 
upload_references
Array of strings (Upload References) 
references of externally uploaded credit notes


 
Responses 
201
Refund order


default
Error response


post/v1/order/{order_id}/refund
Request samples 
application/json
{
  • "reason": "Example reason",
  • "amount": "100.00",
  • "currency": "GBP"
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "amount": "100.00",
  • "currency": "GB",
  • "refund_no": 0,
  • "credit_note_url": "string",
  • "line_items": [
    ],
  • "reason": "Damage",
  • "tax_subtotals": [
    ],
  • "buyer_refund_surcharges": [
    ],
  • "refund_reference": "string",
  • "refund_date": "2019-08-24T14:15:22Z"
}
Create Web client data
Endpoint for merchants to provide data about a user's browser and client. Once the required WebClientData has been added to the request body and the resource has been created successfully, a tracking_id is returned which the merchant should pass along when they create an order later.


SecurityX-Api-Key 
Request 
Request Body schema: application/json
object (WebClientFingerprint) 
 
http_method
string (Http Method) 
 
ip_address
required
string (Ip Address) 
 
user_agent
string (User Agent) 
 
Responses 
201
Endpoint for providing web client data.


default
Error response


post/v1/web_client_data
Request samples 
application/json
{
  • "ip_address": "string",
  • "user_agent": "string",
  • "http_method": "string",
  • "fingerprint": {
    }
}
Response samples 
application/json
{
  • "tracking_id": "string"
}
Invoice
Fetch invoice details
Return an object representing the current status of an invoice, including payment status.


SecurityX-Api-Key 
Request 
path Parameters
order_id
required
string
The ID of the order being queried


 
Responses 
200
OK


404
Order not found


409
Order not invoiced


default
Error response


get/v1/order/{order_id}/invoice_details
Request samples 
Response samples 
application/json
{
  • "payee": {
    },
  • "payment_reference": "string",
  • "payment_reference_type": "string",
  • "payment_reference_message": "string",
  • "payment_reference_ocr": "string",
  • "due_in_days": "30",
  • "invoice_number": "string",
  • "invoicing_group_id": "string",
  • "due_date": "2024-01-31",
  • "id": "ac8f7621-3214-478b-84ad-3f7ada4df83a",
  • "gross_amount": "200.00",
  • "net_amount": "160.00",
  • "tax_amount": "40.00",
  • "total_paid_amount": "0.00",
  • "total_credited_amount": "0.00",
  • "total_collected_amount": "0.00",
  • "total_recoursed_amount": "0.00",
  • "unpaid_amount": "200.00",
  • "statement_number": "123",
  • "billing_period_id": "75bbbadc-95b0-4b4e-bade-3641204a135c",
  • "last_updated": "2023-07-07T13:00:25.552211"
}
Download PDF invoice via Order ID
Endpoint to fetch the invoice for a fulfilled order using the global order ID. The order ID is returned as part of the create order response and is under the key of id at the highest level of the JSON response.


Request 
path Parameters
order_id
required
string
The order id of a fulfilled order


 
query Parameters
generate
boolean (Generate) 
 Default:  "false"
Optional parameter generate (defaults to false) to help with testing or the need to re-create if the template changes etc


 
lang
string (Lang) 
Specify language to generate PDF [en_US, nb_NO, sv_SE]


 
 Example:  lang=en_US
v
string (V) 
Optional parameter v=original to download the original invoice and not the credit note (if any)


 
 Example:  v=original
Responses 
200
OK


default
Error response


get/v1/invoice/{order_id}/pdf
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Download PDF Invoice via Invoice ID
Endpoint to fetch the invoice for a fulfilled order by using the global invoice ID. The invoice ID is provided in the response as part of the invoice_details object with field id.


Request 
path Parameters
invoice_id
required
string
The id of an invoice connected to a fulfilled order


 
Responses 
200
OK


default
Error response


get/v1/invoice/{invoice_id}/document
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Download PDF Invoices in a zip file
Only fulfilled orders can have invoices.


SecurityX-Api-Key 
Request 
query Parameters
generate
boolean (Generate) 
 Default:  "false"
Optional parameter generate (defaults to false) to help with testing or the need to re-create if the template changes etc


 
lang
string (Lang) 
Specify language to generate PDF [en_US, nb_NO, sv_SE]


 
 Example:  lang=en_US
order_id
required
string <uuid>  (Order Id) 
Order IDs of the invoices, provided multiple times as a query parameter


 
v
string (V) 
Optional parameter v=original to download the original invoice and not the credit note (if any)


 
 Example:  v=original
Responses 
200
OK


default
Error response


get/v1/invoice/pdfs
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Change an invoice post fulfillment
This will credit note the current invoice and create a new invoice, with new invoice number, with the requested fields updated. This will not work for overdue invoices or invoices with a status of NOT_PAID.


SecurityX-Api-Key 
Request 
path Parameters
invoice_id
required
string
 
Request Body schema: application/json
object (Billing Address) 
Order billing address


 
buyer_project
string (Buyer Project) 
New value for buyer project on order


 
buyer_purchase_order_number
string (Buyer Purchase Order Number) 
Order purchase number being edited


 
buyer_reference
string (Buyer Reference) 
New value for buyer reference on order


 
Array of objects (Line Item Updates) 
Changes to existing line items


 
order_note
string (Order Note) 
Notes associated with invoice edit


 
Responses 
200
OK


default
Error response


patch/v1/invoice/{invoice_id}
Request samples 
application/json
{
  • "buyer_purchase_order_number": "string",
  • "buyer_reference": "string",
  • "order_note": "string",
  • "buyer_project": "string",
  • "billing_address": {
    },
  • "line_item_updates": [
    ]
}
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
API Key
Create API key
Create a new API key. An existing API key is required to authenticate the request. If you do not have an API key yet, this can be obtained from the merchant portal integration panel. Note that production API key is only available after a manual review once onboarding and integration is complete. The existing key will remain valid until it is revoked.


SecurityX-Api-Key 
Request 
path Parameters
merchant_id
required
string
Merchant ID


 
Responses 
201
API key schema


403
Access denied


404
Merchant not found


default
Error response


post/v1/merchant/{merchant_id}/api_key
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hint": "string",
  • "label": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_last_used": "2019-08-24T14:15:22Z",
  • "date_expiry": "2019-08-24T14:15:22Z",
  • "usage_count": 0,
  • "api_key": "string"
}
Retrieve API keys
Retrieve a list of metadata associated with active API keys.


SecurityX-Api-Key 
Request 
path Parameters
merchant_id
required
string
Merchant ID


 
Responses 
200
List of API key metadata


404
Merchant not found


default
Error response


get/v1/merchant/{merchant_id}/api_key
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieve API key
Retrieve metadata related to an active API key.


SecurityX-Api-Key 
Request 
path Parameters
api_key_id
required
string
API Key ID


 
merchant_id
required
string
Merchant ID


 
Responses 
200
API key metadata


404
Merchant or API key not found


default
Error response


get/v1/merchant/{merchant_id}/api_key/{api_key_id}
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hint": "string",
  • "label": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_last_used": "2019-08-24T14:15:22Z",
  • "date_expiry": "2019-08-24T14:15:22Z",
  • "usage_count": 0
}
Revoke API key
Revoke an existing API key. Once revoked, the key will stop working for subsequent requests.


SecurityX-Api-Key 
Request 
path Parameters
api_key_id
required
string
API Key ID


 
merchant_id
required
string
Merchant ID


 
Responses 
200
API key deleted successfully


403
Access denied


404
Merchant not found


default
Error response


delete/v1/merchant/{merchant_id}/api_key/{api_key_id}
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Settlement report
Download settlement report for a specified period
Endpoint for downloading Two settlement report from start_date to end_date as .xlsx or .csv.


SecurityX-Api-Key 
Request 
query Parameters
country_code
string (Country Code) 
 Default:  "NO"
The country code of the payout account you want to extract a settlement file for. Country code in ISO 3166 alpha-2 format


 
 Example:  country_code=GB
end_date
required
string (End Date) 
The last date that should be included in the statement.


 
 Example:  end_date=2023-01-31
filetype
string (Filetype) 
 Default:  "xlsx"
The filetype of the statement file. Two currently supports csv and xlsx as value for the filetype parameter. Default is xlsx.


 
start_date
required
string (Start Date) 
The first date that should be included in the statement.


 
 Example:  start_date=2023-01-01
Responses 
200
Two settlement report for a specified period.


400
Bad request.


default
Error response


get/v1/portal/merchant/statement
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Download settlement report by its ID
Endpoint for downloading Two settlement report by settlement ID as .xlsx or .csv.


SecurityX-Api-Key 
Request 
query Parameters
filetype
string (Filetype) 
 Default:  "xlsx"
The filetype of the statement file. Two currently supports csv and xlsx as value for the filetype parameter. Default is xlsx.


 
settlement_id
string <uuid>  (Settlement Id) 
The ID of the settlement that belongs to the merchant.


 
Responses 
200
Two settlement report for a specified period.


400
Bad request.


default
Error response


get/v1/portal/merchant/statement-by-settlement-id
Request samples 
Response samples 
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
Get list of settlements for merchant.
SecurityX-Api-Key 
Responses 
200
List of recent payouts from Two


400
Bad request.


default
Error response


get/v1/portal/merchant/settlements
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": {
    }
}