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

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

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. 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"
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",
  • "invoice_type": "FUNDED_INVOICE",
  • "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)

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"
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 for Order.invoice_type == DIRECT_INVOICE Two Bank or a 3rd-party bank for Order.invoice_type == FUNDED_INVOICE Void for Order.invoice_type == CARD

invoice_type
required
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_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)

The order id registered in your solution

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. 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

order_type
string (OrderTypeEnum)

The 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)

The tracking_id from POST /order_intent

vendor_id
string (Vendor Id)

The id of the vendor

vendor_name
string (Vendor Name) non-empty

The name of the vendor

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",
  • "invoice_type": "FUNDED_INVOICE",
  • "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,
  • "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,
  • "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"
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 for Order.invoice_type == DIRECT_INVOICE Two Bank or a 3rd-party bank for Order.invoice_type == FUNDED_INVOICE Void for Order.invoice_type == CARD

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_additional_info
string (Merchant Additional Info)

Additional info the merchant can connect to the order

merchant_order_id
string (Merchant Order Id)

The 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_type": "FUNDED_INVOICE",
  • "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,
  • "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,
  • "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. If the credit check or re-creation fails, then we update order.state to REJECTED. 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": [
    ]
}

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": [
    ]
}

Get associated orders (partial)

This endpoint is used to fetch the associated fulfilled orders for a given partial order ID.

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": [
    ]
}

Partially fulfil order

Endpoint to change to partially fulfill parts of an order based on the line item selection and gross, net amount values. The endpoint changes the state of a specified order to FULFILLED with a status of PARTIAL

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)
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",
  • "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": [
    ]
}

Fulfil order

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
object (UpdateFulfilledOrderSchema)
Responses
200

OK

default

Error response

post/v1/order/{order_id}/fulfilled
Request samples
application/json
{ }
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",
  • "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,
  • "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)

The 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)

The 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": [
    ]
}

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

initiate_payment_to_buyer
required
boolean (Initiate Payment To Buyer)

Initiate payment to buyer

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
{
  • "initiate_payment_to_buyer": true,
  • "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,
  • "initiate_payment_to_buyer": true,
  • "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
browser_fingerprint
string (Browser Fingerprint)
Default: ""
ip_address
required
string (Ip Address)
user_agent
required
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",
  • "browser_fingerprint": ""
}
Response samples
application/json
{
  • "tracking_id": "391f4651-d8a5-4d1e-a427-e2e910f4295f"
}

Invoice

Provide invoice details

The merchant provides invoice details when Order.invoice_type is DIRECT_INVOICE. Two or a 3rd-party bank provides invoice details when Order.invoice_type is FUNDED_INVOICE. Invoice details are void when Order.invoice_type is CARD. The merchant can provide the invoice_details when creating or updating an order, or by using this endpoint.

SecurityX-Api-Key
Request
path Parameters
order_id
required
string

The ID of the order being updated

Request Body schema: application/json
due_date
string <date> (Due Date)
due_in_days
integer (Due In Days)
invoice_emails
Array of strings <email> (Invoice Emails)

We will send invoices to all of the email addresses.

invoice_issue_date
string <date> (Invoice Issue Date)
invoice_number
string (Invoice Number)
object (BankAccountSchema)
payment_reference
string (Payment Reference)
payment_reference_message
required
string (Payment Reference Message)

Text that will be attached to the payment in order for the merchant to reconcile the payment.

payment_reference_ocr
required
string (Payment Reference Ocr)

A string of numbers that will be attached to the payment in order for the merchant to reconcile the payment. E.g. "KID-nummer" in Norway.

payment_reference_type
string (Payment Reference Type)
payment_status
string (PaymentStatusEnum)

An enumeration.

Enum: "NOT_PAID" "PAID" "PARTIAL_PAYMENT" "OVERDUE" "IN_COLLECTIONS" "CANCELLED" "REFUNDED" "PARTIAL_REFUND"
Responses
200

OK

default

Error response

post/v1/order/{order_id}/invoice_details
Request 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"
}
Response samples
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ]
}

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

Endpoint to fetch the invoice for a fulfilled order.

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": [
    ]
}

Download PDF Invoice

Endpoint to fetch the invoice for a fulfilled order by invoice 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": [
    ]
}

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)

The 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": [
    ]
}

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": [
    ]
}

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": [
    ]
}