E-Commerce Service (1.0.0)

Download OpenAPI specification:

Retailer facing API to facilitate a number of e-commerce related functions.

Orders

Create a refund request for a given order.

Description

Authorizations:
BasicAuth
path Parameters
order
required
string

The retailer's unique order ID for the order to be refunded.

Responses

Response samples

Content type
application/json
{
  • "status_code": 201,
  • "message": "Refund created successfully",
  • "data": {
    }
}

Mark an order as completed

Allows you to inform DivideBuy that an order has been completed. This could mean goods have been delivered, or services have been completed.

Authorizations:
BasicAuth
query Parameters
orders
required
Array of arrays

The array of orders you wish to update the settlement date for

orders.*.order_ref_id
required
string

The DivideBuy order ID for this order

orders.*.retailer_order_id
required
string

The retailer’s order ID supplied at the time of order creation

orders.*.retailer_order_ref
required
string

The retailer’s order reference supplied at the time of order creation.

orders.*.date_of_delivery
required
string

Must be in a date format matching YYYY-MM-DD.

Responses

Response samples

Content type
application/json
{
  • "status": 200
}

Quotes

Get the details of a Quote

Description

Authorizations:
BasicAuth
path Parameters
quote
required
string

UUID of the quote

Responses

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "message": "Quote details retrieved successfully.",
  • "data": {
    }
}

Request a new quote.

Creates a request for a new finance quote.

Authorizations:
BasicAuth
query Parameters
customer.title
required
string

Accepts Mr, Mrs, Miss, Ms, Mx, Dr, Prof, Rev

customer.first_name
required
string

Allows both upper and lower case alphabets with spaces, apostrophes, and hyphens up to 50 characters.

customer.last_name
required
string

Allows both upper and lower case alphabets with spaces, apostrophes, and hyphens between 2 to 50 characters.

customer.date_of_birth
required
string

Accepts valid date of birth in YYYY-MM-DD format not younger than 18 years nor older than 100 years

customer.mobile_number
required
string

Accepts valid UK mobile number - should be 11 digits long and begin with 07

customer.address
required
object
customer.address.house_number
string

Accepts any string value up to 12 characters.

customer.address.house_name
string

Accepts any string value up to 50 characters.

customer.address.address_line_1
required
string

Accepts any string value up to 50 characters.

customer.address.address_line_2
string

Accepts any string value up to 50 characters.

customer.address.address_line_3
string

Accepts any string value up to 50 characters.

customer.address.town
required
string

Accepts any string value up to 25 characters.

customer.address.county
string

Accepts any string value up to 100 characters.

customer.address.postcode
required
string

Accepts any string value.

customer.address.time_at_address
string

Must be in the format “YY-MM” where YY is the number of years, and MM is the number of months, that the customer has lived at this address. Either this field, or the following move_in_date field, are required for the current address.

customer.address.move_in_date
string

Accepts a string value representing the date that the customer moved in to this address, in the format YYYY-MM-DD. Either this field, or the previous time_at_address field, are required for the current address.

customer.previous_addresses.*.house_number
string

Accepts any string value up to 12 characters.

customer.previous_addresses.*.house_name
string

Accepts any string value up to 50 characters.

customer.previous_addresses.*.address_line_1
required
string

Accepts any string value up to 50 characters.

customer.previous_addresses.*.address_line_2
string

Accepts any string value up to 50 characters.

customer.previous_addresses.*.address_line_3
string

Accepts any string value up to 50 characters.

customer.previous_addresses.*.town
string

Accepts any string value up to 50 characters.

customer.previous_addresses.*.county
string

Accepts any string value up to 100 characters.

customer.previous_addresses.*.postcode
string

Accepts any string value

customer.previous_addresses.*.time_at_address
required
string

Must be in the format “YY-MM” where YY is the number of years, and MM is the number of months, that the customer has lived at this address. This field is required, if the time_at_address is set on the customer’s current address.

customer.previous_addresses.*.move_in_date
required
string

Accepts a string value representing the date that the customer moved in to this address, in the format YYYY-MM-DD. This field is required, if the move_in_date is set on the customer’s current address.

customer.income_type
required
string

Accepts one of the following values. "Employed full-time, "Employed part-time", "Self employed", "Pension", "Other", "Director of a limited company", Unemployed" or "Retired, not working"

customer.residential_status
required
string

Accepts onr of the following values. "Yes, outright owner", "Yes, with mortgage", "No, renting", "No, other"

customer.customer.ip_address
required
string

The customer’s IP address - a single IP address of either IPv4 or IPv6 format, multiple IPs not supported.

customer.rent
required
string

Accepts integer value in pounds. The rent field is required if the residential status is not selected as “Yes, outright owner”, or “No, other” option.

customer.customer.nationality
required
string

Must be a string and match an existing nationality found in this list https://www.gov.uk/government/publications/nationalities/list-of-nationalities

order.retailer_order_id
required
string

The internal ID for the related order

order.retailer_order_ref
required
string

The internal reference for the related order (if not available, the ID can be sent again)

order.selected_instalment_term
required
number

The number of months the customer is requesting to spread the cost of their order over. This must be equal to one of the agreed terms you have enabled by us, other values will return an error.

order.instalment_date
required
number

The date of each month that the customer would like to make their payments. Accepts integer values between 1 to 31.

order.subtotal
required
number

Subtotal of order in pounds

order.vat_rate
number

The VAT rate as a percentage (i.e. 20 for 20% VAT). If the VAT rate is not provided, we will use the rate we have configured for your account internally. We recommend providing this value where possible to ensure you are in control of the specific details of your orders.

order.vat
number

Subtotal of order in pounds

order.shipping
required
number

Shipping total in pounds

order.shipping_method
required
string

Shipping method - typically an identifier for the shipping method such as ‘free_shipping’ or ‘express’ etc.

order.shipping_label
required
string

A more detailed description of the shipping method, i.e. “Free Shipping” or “Next-Day Delivery” etc.

order.discount
required
string

Total amount of discount on the order, in pounds

order.time_discount_applied
required
string

When the discount is calculated within the order total. For more cases this will be beforeVat, with VAT only being applicable to the amount paid by the customer. Accepts beforeVat or afterVat.

order.total
required
string

Order total in pounds

order.is_default_shipping
required
boolean

Boolean value to state if the shipping address is the customer’s default shipping address - accepts 1 or 0

order.is_default_billing
required
boolean

Boolean value to state if the billing address is the customer’s default billing address - accepts 1 or 0

order.upfront_payment
required
boolean

The total the customer has paid upfront, in pounds. Please note - any upfront payments must be collected by yourselves before redirecting your customer to us to complete their application for the remainder of the amount.

order.credit_amount
required
boolean

The amount of credit being requested, in pounds. This is the order total, minus any upfront payment.

order.source
required
string

A representation of the sales channel used to generate this quote. For e-commerce/web orders, this field is not required, however for other channels - due to regulatory requirements - we are required to know the source or sales channel of the quote. For any of the following sales channels, the following value should be supplied here "Web orders (ecommerce/app) → not required", "Orders sold in store → in-store", "Orders created over the phone (telesales) → telephony" or "Orders created via a home visit → in-home"

order.line_items
Array of arrays

An array of the line items that the order contains. Providing a line item breakdown of the order is not required, but to aid you and us to cross reference the details of orders for any queries, it is advised where possible to provide this information.

order.line_items.*.name
required
string

The name of the line item.

order.line_items.*.sku
string

The SKU of the item.

order.line_items.*.quantity
required
integer

The quantity of this item in the order

order.line_items.*.price_excluding_vat
required
number

order.line_items.*.quantity

order.line_items.*.price_including_vat
required
number

The price of the item, including any VAT. At least one of these parameters

order.line_items.*.vat_percentage
number

The percentage of VAT applied to this item. If not provided, the value configured on your retailer account will be used.

order.line_items.*.row_total_excluding_vat
number

The total cost for this item, excluding VAT. Equates to the unit cost excluding VAT, multiplied by the quantity. If not provided, the value will be calculated using the details configured on your retailer account.

order.line_items.*.row_total_including_vat
number

The total cost for this item, including VAT. Equates to the unit cost including VAT, multiplied by the quantity. If not provided, the value will be calculated using the details configured on your retailer account.

order.line_items.*.discount
number

The amount of discount applied directly to this line item, in pounds. If not provided, the value will be set to 0.

order.redirect_url
string

Accepts a valid URL that can be used to redirect the customer from our checkout, in the instance any unexpected errors occur. This value is optional, but if provided will allow us to redirect the customer to a URL specified by you in order for you to continue to manage the customer journey. The URL must be a valid URL, but you are free to add query parameters as you like, which will be preserved at the time of redirection.

payment
object

An optional object describing the intended payment details.

payment.method
required
string

Describes the payment method for the order. Currently the only acceptable value for this is direct_debit. Only accounts with explicit permission to pay via Direct Debit will be able to supply payment details here

payment.sort_code.
string

The sort code of the account to be used for a Direct Debit payment. Must be an 6 character long string, and contain only digits (0-9). Please remove any hyphens or spaces before requesting a quote. Required if payment.method is direct_debit.

payment.account_number
string

The account number of the account to be used for a Direct Debit payment. Must be an 8 character long string, and contain only digits (0-9). Please remove any hyphens or spaces before requesting a quote. Required if payment.method is direct_debit.

payment.account_name
string

The name registered on the account to be used for payment. If not provided, it will default to using a combination of the customer.first_name and customer.last_name fields.

Responses

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "message": "Request completed successfully.",
  • "data": {
    }
}

Authentication

Issue Access Token (Client Credentials Grant)

Exchanges client credentials (client_id and client_secret) for an access token using the OAuth 2.0 Client Credentials Grant flow.

Authorizations:
BasicAuth
header Parameters
Authorization
required
string

Format: Basic {base64(client_id:client_secret)}

Request Body schema: application/json
required
grant_type
required
string
Value: "client_credentials"

The OAuth 2.0 grant type. Must be set to client_credentials.

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Terms

Fetch instalment terms.

Successful response may contain available and non-available terms (indicated by available flag).

query Parameters
amount
required
number
Example: amount=2000

The product or total order amount.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "Terms fetched successfully"
}

Representative Example

Fetch representative example.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "Representative Example fetched successfully"
}