Orders

Order Model

Properties

  • Name
    id
    Type
    string
    Description

    The unique ID of the order.

  • Name
    customer
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The unique ID of the customer thtat the order is associated with.

  • Name
    name
    Type
    string,null
    Restrictions
    Description

    A name for the order. This is generally a short identifier for the order, such as #2892 or #OD-543678.

    This is generally what will be displayed as the order reference, and may be identical to the order ID or marketplace order ID.

    This key is not used as a reference to the resource in any other endpoints.

  • Name
    note
    Type
    string,null
    Restrictions
    Description

    An optional note that is attached to the order. This note will generally be left by or on behalf of the customer.

    If looking to add a note for something such as a gift message, the suggestion is that this should go in the order metadata.

    We are considering adding a staff_notes parameter that is not displayed on any customer facing interfaces, please contact us if this is something that you would like to see added.

  • Name
    marketplace
    Type
    object,null
    Restrictions
    Description

    The details of the marketplace and external identifier that corresponds to this order if the order was originally placed on an external marketplace, otherwise this field will be null.

  • Name
    » platform
    Type
    string
    Restrictions
    Description

    The identifier for the marketplace/platform.

    The identifier must be one of the allowed marketplace identifiers, attempting to use an invalid identifier will cause the request to fail.

  • Name
    » id
    Type
    string
    Restrictions
    Description

    The order identifier on the external marketplace.

    If provided, this order will be linked to the specified marketplace, and where supported, will monitor for updates to the order on the external marketplace.

  • Name
    metadata
    Type
    object
    Restrictions
    Description

    An object containing a series of key/value pairs of metadata that will be attached to the order.

    A maximum of 50 pairs is allowed. Keys and values must both be strings containing alphanumeric characters.

  • Name
    » ^[a-zA-Z0-9_]{0,50}$
    Type
    string
    Restrictions
    Description

    An arbitrary key/value pair.

    Keys can contain alphanumeric characters and underscores, values can contain UTF-8 text. Keys can be up to 50 characters in length, values up to 500.

  • Name
    line_items
    Type
    [[OrderLineItem](#schemaorderlineitem)]
    Restrictions
    Description

    [Represents a line item for a given order.

    Holds information about the product, along with additional information related to the orders, such as quantity ordered and corresponding shipping address.]

  • Name
    committed_at
    Type
    string,null(date-time)
    Description

    An RFC 3339 timestamp for when the order was saved/committed.

    If the order has not been committed yet, this field will be null.

  • Name
    shipping_details
    Type
    array,null
    Restrictions
    Description
  • Name
    payment_details
    Type
    array,null
    Restrictions
    Description
  • Name
    current_status
    Type
    object
    Restrictions
    Description
  • Name
    » order
    Type
    [OrderStatusEvent](#schemaorderstatusevent)
    Restrictions
    Description
  • Name
    » payment
    Type
    [OrderStatusEvent](#schemaorderstatusevent)
    Restrictions
    Description
  • Name
    » fulfilment
    Type
    [OrderStatusEvent](#schemaorderstatusevent)
    Restrictions
    Description
  • Name
    prices
    Type
    [Price](#schemaprice)
    Restrictions
    Description

    The summary price data for all items included in the order.

  • Name
    refunds
    Type
    array,null
    Restrictions
    Description
  • Name
    on_hold
    Type
    boolean,null
    Restrictions
    Description

    Whether the order is on hold. An order can only be put on hold and removed from hold manually, there is no automatic status change that causes the hold state to change.

  • Name
    hold_description
    Type
    string,null
    Restrictions
    Description

    If the order is put on hold a description for why the order has been put on hold must also be provided.

  • Name
    alternative_identifiers
    Type
    array,null
    Restrictions
    Description

    An optional array containing any alternative identifiers for the order - these may occur as a result of multiple systems in the oprder process assigning different identifiers, hence this field can be used to track and collate them.

{
  "id": "ord_1HCpXwx2EK9oYluWbacgeCnFcLf",
  "customer": {
    "id": "cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"
  },
  "name": "#42196",
  "note": "Please leave the package in the parcel bin if I'm not home during delivery.",
  "marketplace": {
    "platform": "shopify",
    "id": "1073459966"
  },
  "metadata": {
    "hs_tariff_code": "1982740100"
  },
  "line_items": [
    {
      "id": "li_29U5Okdr6frqFyaa5wo6E9vWDma",
      "is_custom": false,
      "product": {
        "id": "prod_29U5Okw4MkbHiAkMg20Ukx8eKhj",
        "name": "SuperZap Microwave",
        "variant": {
          "id": "vrnt_29U5Ojl3byzXQ0Eotk3e1917t21",
          "name": "Black 3000W",
          "gtin": "84012345123452",
          "sku": "SZ-MIC-3000-B"
        }
      },
      "marketplace": {
        "platform": "shopify",
        "id": "1073459966"
      },
      "metadata": {
        "hs_tariff_code": "1982740100"
      },
      "shipping_detail": {
        "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP"
      },
      "quantity": 1,
      "shipping_required": true,
      "discounts": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "code": "30OFFTDC",
          "description": "30% Off - Trade Discount",
          "amount": 500,
          "currency_code": "GBP"
        }
      ],
      "tax_lines": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "name": "VAT (Standard 20%)",
          "type": "inclusive",
          "amount": 1200,
          "currency_code": "GBP",
          "rate": 0.2
        }
      ],
      "prices": {
        "unit": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "line_total": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "currency_code": "GBP"
      }
    }
  ],
  "committed_at": "2022-03-26T15:47:19Z",
  "shipping_details": [
    {
      "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
      "carrier_code": "UPS",
      "carrier_service_code": "SV",
      "method_name": "UPS Worldwide Saver",
      "method_identifier": "UPSWorldwideSaver",
      "prices": {
        "base": 42000,
        "discount": 35000,
        "tax": 35000,
        "subtotal": 7000,
        "total": 0.2,
        "tax_rates": {
          "additive": 0.18,
          "inclusive": 0.2,
          "blended": 0.38
        },
        "currency_code": "GBP"
      },
      "shipping_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      }
    }
  ],
  "payment_details": [
    {
      "id": "pd_2AJzG3TRewYEJMUwSCwv7VPtMZb",
      "payment_info": {
        "transaction_details": {
          "gateway": "stripe",
          "reference": null,
          "token": "ch_3L8Qnd2eZvKYlo2C1SNDmEfL",
          "high_risk": false,
          "method": {}
        },
        "card_details": {
          "last4": "5710",
          "exp_month": 8,
          "exp_year": 2025,
          "country_code": "US",
          "cardholder_name": "Jamie Foster",
          "company": "Mastercard",
          "bin": "400344"
        },
        "amount": 4500,
        "currency_code": "USD"
      },
      "status": "succeeded",
      "billing_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      },
      "created_at": "2021-07-25T14:37:43.68Z",
      "updated_at": "2021-07-25T14:37:43.68Z"
    }
  ],
  "current_status": {
    "order": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "payment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "fulfilment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    }
  },
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "refunds": [
    {
      "id": "re_2YlgkP2OGf8NpnA3CyOvpuo6W34",
      "status": "refunded",
      "description": "shipment arrived late to customer, goodwill refund.",
      "amount": 500,
      "currency_code": "GBP",
      "created_at": "2022-05-02T20:00:35.476360Z",
      "updated_at": "2022-05-02T20:00:35.476360Z"
    }
  ],
  "on_hold": true,
  "hold_description": "string",
  "alternative_identifiers": [
    "RHRUESFBG9"
  ]
}

Order Address Model

Properties

  • Name
    Order Address
    Type
    any
    Restrictions
    Description

    An extension of the base address model.

    This model is identical to the Address model save for two features:

    - The id parameter returned for an order address receives the prefix oa instead of addr, and only exists in the context of an order - it cannot be queried via the usual customer address endpoints.
    - The display_name field of the address is always null, as this address is not subject to reuse, hence the display name is unnecessary.

    In the event that an order contains multiple items being shipped to multiple addresses, each line item will reference the id to indicate which address it should be shipped to.

    N.B. If the order is created with the address being supplied as the ID of an address that is already associated with the customer, internally a copy of the address data is stored at the point that the order is created. This does not currently include the address metadata, but may do so at a later point in time.

  • Name
    *anonymous*
    Type
    [Address](#schemaaddress)
    Restrictions
    Description
  • Name
    *anonymous*
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Description

    The ID of the order address record.

    In the event that an address ID is passed to populate this address, the address ID (prefixed with addr) is not stored, as internally a copy of the address is made at the point the order is created.

  • Name
    » display_name
    Type
    null
    Restrictions
    Description

    For order addresses, the display name is always null.

{
  "address": {
    "line_1": "29 Holgate Rd",
    "line_2": "Segwick Street",
    "line_3": "Kelvedon",
    "city": "RACKWICK",
    "province": "Cambershire",
    "post_code": "KW16 2PE",
    "country_code": "GB"
  },
  "contact": {
    "name": "Francesca Brady",
    "company": "Malvinex Corp"
  },
  "display_name": null,
  "metadata": {
    "contact_email": "[email protected]"
  },
  "marketplaces": {
    "shopify": "657847832011"
  },
  "coordinates": {
    "latitude": 51.5134297,
    "longitude": -0.103145,
    "confidence": 1
  },
  "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
}

Order Discount Model

Properties

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique ID for the discount in this order.

  • Name
    code
    Type
    string,null
    Restrictions
    Description

    The discount code used by the customer.

  • Name
    description
    Type
    string,null
    Restrictions
    Description

    A description for the discount. May be displayed as a title in some places.

  • Name
    amount
    Type
    integer
    Restrictions
    Description

    A positive integer representing the absolute amount of the discount in the smallest unit of the specified currency.

  • Name
    currency_code
    Type
    string,null
    Restrictions
    Description

    The 3-letter ISO 4217 currency code. This is populated from the order, and cannot be specified/updated here currently.

{
  "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
  "code": "30OFFTDC",
  "description": "30% Off - Trade Discount",
  "amount": 500,
  "currency_code": "GBP"
}

Order Tax Line Model

Properties

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique ID for the discount in this order.

  • Name
    name
    Type
    string
    Restrictions
    Description

    The name of the tax that will be displayed to users & customers.

  • Name
    type
    Type
    string
    Restrictions
    Description

    A description for the discount. May be displayed as a title in some places.

    Possible Enum Values

    inclusive
    additive
  • Name
    amount
    Type
    integer
    Restrictions
    Description

    A positive integer representing the absolute amount of the discount in the smallest unit of the specified currency.

  • Name
    currency_code
    Type
    string,null
    Restrictions
    Description

    The 3-letter ISO 4217 currency code. This is populated from the order, and cannot be specified/updated here currently.

  • Name
    rate
    Type
    number,null
    Restrictions
    Description

    The percentage tax rate represented as a decimal.

{
  "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
  "name": "VAT (Standard 20%)",
  "type": "inclusive",
  "amount": 1200,
  "currency_code": "GBP",
  "rate": 0.2
}

Order Refund Model

Properties

  • Name
    id
    Type
    string,null
    Restrictions
    Description

    The unique ID of the refund for the order.

  • Name
    status
    Type
    string
    Restrictions
    Description

    The status of the refund.

    Possible Enum Values

    refunded
    failed
    processing
  • Name
    description
    Type
    string,null
    Restrictions
    Description

    An optional description for the reason for the refund.

  • Name
    amount
    Type
    integer
    Restrictions
    Description

    The amount of the refund in the smallest unit of the currency.

  • Name
    currency_code
    Type
    string,null
    Restrictions
    Description

    The currency code for the refund. Currently this is populated from the order currency code.

    If you need to be able to refund in currencies other than the order currency, please contact support for more information.

  • Name
    created_at
    Type
    string,null(date-time)
    Restrictions
    Description

    The timestamp for when the refund was created.

  • Name
    updated_at
    Type
    string,null(date-time)
    Restrictions
    Description

    The timestamp for when the refund was most recently updated.

{
  "id": "re_2YlgkP2OGf8NpnA3CyOvpuo6W34",
  "status": "refunded",
  "description": "shipment arrived late to customer, goodwill refund.",
  "amount": 500,
  "currency_code": "GBP",
  "created_at": "2022-05-02T20:00:35.476360Z",
  "updated_at": "2022-05-02T20:00:35.476360Z"
}

Order Line Item Model

Properties

  • Name
    id
    Type
    string
    Description

    The unique ID for the line item.

  • Name
    is_custom
    Type
    boolean
    Restrictions
    Description

    Whether the item is a custom line item.

  • Name
    product
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The unique ID of the product.

  • Name
    » name
    Type
    string,null
    Restrictions
    Description

    The name of the product.

  • Name
    » variant
    Type
    object
    Restrictions
    Description

    The specific variant of the product and accompanying details.

  • Name
    » id
    Type
    string
    Restrictions
    Description

    The unique product variant ID.

  • Name
    » name
    Type
    string,null
    Restrictions
    Description

    A variant-specific name. May be null in the event that no name is set, or the product is a single variant product, in which case the additional name may be redundant.

  • Name
    » gtin
    Type
    string,null
    Restrictions
    Description

    The GTIN for the product variant.

  • Name
    » sku
    Type
    string,null
    Restrictions
    Description

    The SKU for the product.

  • Name
    marketplace
    Type
    object,null
    Restrictions
    Description

    The details of the marketplace and external identifier that corresponds to this order line item if the order was originally placed on an external marketplace, otherwise this field will be null.

  • Name
    » platform
    Type
    string
    Restrictions
    Description

    The identifier for the marketplace/platform.

    The identifier must be one of the allowed marketplace identifiers, attempting to use an invalid identifier will cause the request to fail.

  • Name
    » id
    Type
    string
    Restrictions
    Description

    The order line item identifier on the external marketplace.

    If provided, this order line item will be linked to the specified marketplace, and where supported, will monitor for updates to the order on the external marketplace.

  • Name
    metadata
    Type
    object
    Restrictions
    Description

    An object containing a series of key/value pairs of metadata that will be attached to the line item.

    A maximum of 50 pairs is allowed. Keys and values must both be strings containing alphanumeric characters.

    Metadata is generally used to store product customisation attributes, eg. If a product has customer specified laser engraving, the metadata might contain `"laser_message": "Johnny's Ratchet - Hands Off!"

  • Name
    » ^[a-zA-Z0-9_]{0,50}$
    Type
    string
    Restrictions
    Description

    An arbitrary key/value pair.

    Keys can contain alphanumeric characters and underscores, values can contain UTF-8 text. Keys can be up to 50 characters in length, values up to 500.

  • Name
    shipping_detail
    Type
    object
    Restrictions
    Description

    Contains a reference to the ID of the order address in the shipping_addresses field that this line item is to be shipped to.

    For orders containing items that will be shipped to multiple addresses, this allows one to correlate a given line item with the one or more addresses attached to an order.

    In the event that the order only has one shipping address, or is not specified by the client, the ID will correspond to the first address in the shipping address array.

  • Name
    » id
    Type
    string,null
    Restrictions
    Description

    The ID corresponding to the matching id in the shipping_details field of the Order model that this line item is linked to.

    The ID will be an Order Address ID, prefixed with oa.

    May be null for orders with one of less shipping addresses present. Where this is unspecified at order creation, the ID here will correspond to the first address in the first entry of the shipping_details field.

  • Name
    quantity
    Type
    integer
    Restrictions
    Description

    The quantity of the item ordered.

  • Name
    shipping_required
    Type
    boolean,null
    Restrictions
    Description

    Whether the line item required shipping.

  • Name
    discounts
    Type
    array,null
    Restrictions
    Description

    An array of discounts that apply to the current line item.

  • Name
    tax_lines
    Type
    array,null
    Restrictions
    Description

    An array of tax rates that apply to the current line item.

  • Name
    prices
    Type
    object
    Restrictions
    Description
  • Name
    » unit
    Type
    [Price](#schemaprice)
    Restrictions
    Description

    The prices corresponding to the current line item on a per unit basis.

  • Name
    » line_total
    Type
    [Price](#schemaprice)
    Restrictions
    Description

    The prices corresponding to the current line item on a line total basis, i.e. product price per unit * quantity

  • Name
    » currency_code
    Type
    string
    Restrictions
    Description

    The 3-letter ISO 4217 currency code for the order.

{
  "id": "li_29U5Okdr6frqFyaa5wo6E9vWDma",
  "is_custom": false,
  "product": {
    "id": "prod_29U5Okw4MkbHiAkMg20Ukx8eKhj",
    "name": "SuperZap Microwave",
    "variant": {
      "id": "vrnt_29U5Ojl3byzXQ0Eotk3e1917t21",
      "name": "Black 3000W",
      "gtin": "84012345123452",
      "sku": "SZ-MIC-3000-B"
    }
  },
  "marketplace": {
    "platform": "shopify",
    "id": "1073459966"
  },
  "metadata": {
    "hs_tariff_code": "1982740100"
  },
  "shipping_detail": {
    "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP"
  },
  "quantity": 1,
  "shipping_required": true,
  "discounts": [
    {
      "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
      "code": "30OFFTDC",
      "description": "30% Off - Trade Discount",
      "amount": 500,
      "currency_code": "GBP"
    }
  ],
  "tax_lines": [
    {
      "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
      "name": "VAT (Standard 20%)",
      "type": "inclusive",
      "amount": 1200,
      "currency_code": "GBP",
      "rate": 0.2
    }
  ],
  "prices": {
    "unit": {
      "base": 42000,
      "discount": 35000,
      "tax": 35000,
      "subtotal": 7000,
      "total": 0.2,
      "tax_rates": {
        "additive": 0.18,
        "inclusive": 0.2,
        "blended": 0.38
      },
      "currency_code": "GBP"
    },
    "line_total": {
      "base": 42000,
      "discount": 35000,
      "tax": 35000,
      "subtotal": 7000,
      "total": 0.2,
      "tax_rates": {
        "additive": 0.18,
        "inclusive": 0.2,
        "blended": 0.38
      },
      "currency_code": "GBP"
    },
    "currency_code": "GBP"
  }
}

Order Payment Detail Model

Properties

  • Name
    id
    Type
    string
    Description
  • Name
    payment_info
    Type
    object
    Restrictions
    Description
  • Name
    » transaction_details
    Type
    object
    Restrictions
    Description
  • Name
    » gateway
    Type
    string
    Restrictions
    Description

    The identifier for the gateway used to process the payment.

    For payments processed by the merchant with no intermediary, a value of direct can be used.

  • Name
    » reference
    Type
    null,string
    Restrictions
    Description
  • Name
    » token
    Type
    string
    Restrictions
    Description
  • Name
    » high_risk
    Type
    boolean
    Restrictions
    Description
  • Name
    » method
    Type
    object
    Restrictions
    Description
  • Name
    » type
    Type
    string
    Restrictions
    Description

    The type of payment used.

    For online processors this may be card, bacs, swift, etc.

    For payments processed directly by the merchant, it could be one of cash, cheque, etc.

  • Name
    » token
    Type
    string
    Restrictions
    Description

    A token identifying the resource used for the payment. This will typically be returned by the payment gateway as part of the transaction.

  • Name
    » card_details
    Type
    object
    Restrictions
    Description
  • Name
    » last4
    Type
    null,string
    Restrictions
    Description

    For card payments, the last 4 digits of the card used.

  • Name
    » exp_month
    Type
    null,integer
    Restrictions
    Description
  • Name
    » exp_year
    Type
    null,integer
    Restrictions
    Description
  • Name
    » country_code
    Type
    null,string
    Restrictions
    Description
  • Name
    » cardholder_name
    Type
    null,string
    Restrictions
    Description
  • Name
    » company
    Type
    string,null
    Restrictions
    Description

    The name of the company that issued the card.

  • Name
    » bin
    Type
    string,null
    Restrictions
    Description

    The Bank Identification Number (BIN) for the card, if present.

  • Name
    » amount
    Type
    integer
    Restrictions
    Description
  • Name
    » currency_code
    Type
    string
    Restrictions
    Description
  • Name
    status
    Type
    string
    Restrictions
    Description

    Possible Enum Values

    succeeded
    failed
    processing
    requires_action
    error
    unknown
  • Name
    billing_address
    Type
    [OrderAddress](#schemaorderaddress)
    Restrictions
    Description

    An extension of the base address model.

    This model is identical to the Address model save for two features:

    - The id parameter returned for an order address receives the prefix oa instead of addr, and only exists in the context of an order - it cannot be queried via the usual customer address endpoints.
    - The display_name field of the address is always null, as this address is not subject to reuse, hence the display name is unnecessary.

    In the event that an order contains multiple items being shipped to multiple addresses, each line item will reference the id to indicate which address it should be shipped to.

    N.B. If the order is created with the address being supplied as the ID of an address that is already associated with the customer, internally a copy of the address data is stored at the point that the order is created. This does not currently include the address metadata, but may do so at a later point in time.

  • Name
    created_at
    Type
    string(date-time)
    Restrictions
    Description
  • Name
    updated_at
    Type
    string(date-time)
    Restrictions
    Description
{
  "id": "pd_2AJzG3TRewYEJMUwSCwv7VPtMZb",
  "payment_info": {
    "transaction_details": {
      "gateway": "stripe",
      "reference": null,
      "token": "ch_3L8Qnd2eZvKYlo2C1SNDmEfL",
      "high_risk": false,
      "method": {
        "type": "card",
        "token": "pm_1L6ZIF2eZvKYlo2Cn6OzyDVs"
      }
    },
    "card_details": {
      "last4": "5710",
      "exp_month": 8,
      "exp_year": 2025,
      "country_code": "US",
      "cardholder_name": "Jamie Foster",
      "company": "Mastercard",
      "bin": "400344"
    },
    "amount": 4500,
    "currency_code": "USD"
  },
  "status": "succeeded",
  "billing_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  },
  "created_at": "2021-07-25T14:37:43.68Z",
  "updated_at": "2021-07-25T14:37:43.68Z"
}

Order Shipping Detail Model

Properties

  • Name
    id
    Type
    string
    Description

    The unique ID for the shipping detail.

  • Name
    carrier_code
    Type
    string,null
    Restrictions
    Description

    The carrier code.

  • Name
    carrier_service_code
    Type
    string,null
    Restrictions
    Description

    The carrier specific service code.

  • Name
    method_name
    Type
    string
    Restrictions
    Description

    The shipping method name. This is required and is generally the name of the shipping method as presented to the customer.

  • Name
    method_identifier
    Type
    string
    Restrictions
    Description

    The identifier for the shipping method. Should be constant across all orders with the same shipping method.

    Also used for mapping order shipping methods to fulfilment shipping methods.

  • Name
    prices
    Type
    [Price](#schemaprice)
    Restrictions
    Description

    Holds price information for a given resource.

    All prices are stored in the respective currency's smallest unit. For example, $25 (USD) is stored as 2500, meaning 2500 cents.

    The currency_code field accepts a 3-letter ISO 4217 currency code. Providing a code that is not defined as part of ISO 4217 will result in an error.

    The tax_rates fields hold the tax rate if applicable, represented as a decimal. The decimal representation is stored with 4 decimal places of accuracy, with the normal rules of rounding applying, ie. 0.25255 is saved as 0.2526, and 0.25254 saved as 0.2525.

    We recommend that client applications do not send a tax_rate with more than 4 decimal places of accuracy; any tax rate with more than 4 decimal places will be rounded accordingly.

    The only field that is directly editable is the base price. The other fields are calculated.

    The fields are calculated as follows:

    - base: The base price for the current entity, including any inclusive taxes. The proportion of the base price that is comprised of inclusive taxes is usually specified in the tax_lines field of the entity.

    - discount: The amount in absolute terms of discount applied to the current entity. Discounts should be represented as a positive integer - negative integers will be rejected. The discount amount cannot exceed the base amount.

    - tax: The amount in absolute terms of tax applied to the current entity, both inclusive & additive. This must be a positive integer. The tax amount cannot exceed the base amount.

    - subtotal: Calculated as the base amount minus the discount amount, excluding any additive taxes.

    - total: The subtotal amount, plus any additive taxes that are due. This is generally the amount that the customer is expected to pay.

    For resources where external pricing modifiers may be at play, such as discount and promotions, these are reflected in the difference between the base price and net price.

  • Name
    shipping_address
    Type
    [OrderAddress](#schemaorderaddress)
    Restrictions
    Description

    An extension of the base address model.

    This model is identical to the Address model save for two features:

    - The id parameter returned for an order address receives the prefix oa instead of addr, and only exists in the context of an order - it cannot be queried via the usual customer address endpoints.
    - The display_name field of the address is always null, as this address is not subject to reuse, hence the display name is unnecessary.

    In the event that an order contains multiple items being shipped to multiple addresses, each line item will reference the id to indicate which address it should be shipped to.

    N.B. If the order is created with the address being supplied as the ID of an address that is already associated with the customer, internally a copy of the address data is stored at the point that the order is created. This does not currently include the address metadata, but may do so at a later point in time.

{
  "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
  "carrier_code": "UPS",
  "carrier_service_code": "SV",
  "method_name": "UPS Worldwide Saver",
  "method_identifier": "UPSWorldwideSaver",
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "shipping_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  }
}

Price Model

Properties

  • Name
    base
    Type
    integer,null
    Restrictions
    Description

    The price excluding any discounts, and additive taxes, but including any inclusive taxes.

  • Name
    discount
    Type
    integer,null
    Restrictions
    Description

    The discount amount applied to the current entity.

    This cannot be greater than the base amount.

  • Name
    tax
    Type
    integer,null
    Restrictions
    Description

    The amount of inclusive & additive tax that applies the the entity.

    This cannot be greater than the base amount.

  • Name
    subtotal
    Type
    integer,null
    Restrictions
    Description

    The price including any inclusive taxes, minus the discount amount.

  • Name
    total
    Type
    number,null
    Restrictions
    Description

    The price including discounts, inclusive & exclusive taxes.

  • Name
    tax_rates
    Type
    [TaxRate](#schemataxrate)
    Restrictions
    Description

    Contains the inclusive, additive & blended tax rates for the entity, represented as decimals between 0 & 1 with 4 decimal places of accuracy.

    Please note that these rates are approximate, and are intended for observational/analytical use - they should not be relied upon for official tax calculations.

  • Name
    currency_code
    Type
    string,null
    Restrictions
    Description

    The 3-letter ISO 4217 currency code for the included prices.

    If this property is null, the assumption is that the prices are displayed in the store's primary currency.

{
  "base": 42000,
  "discount": 35000,
  "tax": 35000,
  "subtotal": 7000,
  "total": 0.2,
  "tax_rates": {
    "additive": 0.18,
    "inclusive": 0.2,
    "blended": 0.38
  },
  "currency_code": "GBP"
}

Tax Rate Model

Properties

  • Name
    Tax Rate
    Type
    object,null
    Restrictions
    Description
  • Name
    additive
    Type
    number,null
    Restrictions
    Description

    The tax rate as a proportion of the base amount for all taxes that are in addition to the base amount.

    N.B. The additive rate is calculated against the base price which includes any inclusive taxes. If the user desires the additive rate calculated on the basis of the base amount excluding any inclusive taxes then the user must calculate this themselves.

  • Name
    inclusive
    Type
    number,null
    Restrictions
    Description

    The tax rate as a proportion of the base amount for all taxes that are included in the base amount.

  • Name
    blended
    Type
    number,null
    Restrictions
    Description

    The overall tax rate, calculated as the sum of the additive and inclusive tax rates.

{
  "additive": 0.18,
  "inclusive": 0.2,
  "blended": 0.38
}

Order Status Event Model

Properties

  • Name
    code
    Type
    string
    Required
    required
    Restrictions
    Description

    A status code for the event. A list of all available status codes can be found in the Status Codes article.

  • Name
    description
    Type
    string
    Restrictions
    Description

    A description for the status event.

    Not always present, used to add additional context for why a status event was added.

  • Name
    created_at
    Type
    string(date-time)
    Restrictions
    Description

    A timestamp for when the status event was created. Used for displaying events in the order that they occurred.

{
  "code": "ORDER_CONFIRMED",
  "description": "Payment received and order committed, order has been confirmed.",
  "created_at": "2022-06-16T18:40:22.717563"
}
POST/orders

Create Order

Create an order.

It is highly recommended that anyone looking to use the Orders API familiarises themself with the architecture and behaviour of the orders resource, as described in the article on orders.

This endpoint requires the client to lookup (and where necessary, create) the Customer, Product & Addresses that will be used in the order.

In the event that the referenced resource (eg. the customer address) needs to be modified, the client can pass in the fields that are to be modified without needing to provide the complete resource object. In the example below, the shipping_details instance will be populated from the existing customer address with ID addr_28ci3lu2plw2wice8uedJWKJSWW, but the contact name will be overwritten from the stored address with the name James Baker.

The portion of the request body is as follows:

"shipping_details": [
  {
    "carrier_code": "UPS",
    "carrier_service_code": "SV",
    ...
    "shipping_address": {
      "id": "addr_28ci3lu2plw2wice8uedJWKJSWW",
      "contact": {
        "name": "James Baker"
      }
    }
  }
]

It should be noted that any modifications to the referenced resource do not propagate to the underlying resource - the modifications are only associated with the current order. If the underlying resource should be modified permanently, the changes should first be made to the underlying resource and the order created subsequently.

Committing an Order

For an order to be eligible for fulfilment, it must be in the committed state.

As described in the article on orders, orders are by default created in the committed state, unless instructed otherwise. To prevent an order being created in the committed state, pass the auto_commit query parameter with a value of false.

Creating uncommitted orders may be necessary for more complex orders, in which case the order must be manually committed before fulfilment can occur.

Notes on Future Developments

In addition to the read only fields, we do not support passing metadata for referenced resources currently. Metadata can be provided for the main Order object, and for the individual Order Line Item objects. Resources with metadata such as products will use the metadata stored on the upstream product. This will likely change in future to allow metadata for referenced resources to be passed.

Query Parameters

  • Name
    auto_commit
    Type
    boolean
    Restrictions
    Description

    Whether the order should be automatically committed upon creation.

  • Name
    status_log
    Type
    boolean
    Restrictions
    Description

    Whether the order response contains the full log of status codes, past and present.

Request

POST
/orders
curl --request POST \
--url https://api.envoy.one/orders \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"customer":{"id":"cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"},"name":"#42196","note":"Please leave the package in the parcel bin if I'\''m not home during delivery.","marketplace":{"platform":"shopify","id":"1073459966"},"metadata":{"hs_tariff_code":"1982740100"},"line_items":[{"is_custom":false,"product":{"id":"prod_29U5Okw4MkbHiAkMg20Ukx8eKhj","name":"SuperZap Microwave","variant":{"id":"vrnt_29U5Ojl3byzXQ0Eotk3e1917t21","name":"Black 3000W","gtin":"84012345123452","sku":"SZ-MIC-3000-B"}},"marketplace":{"platform":"shopify","id":"1073459966"},"metadata":{"hs_tariff_code":"1982740100"},"shipping_detail":{"id":"sd_2AINeixtljsn5YPYsmemIAUWGFP"},"quantity":1,"shipping_required":true,"discounts":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","code":"30OFFTDC","description":"30% Off - Trade Discount","amount":500,"currency_code":"GBP"}],"tax_lines":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","name":"VAT (Standard 20%)","type":"inclusive","amount":1200,"currency_code":"GBP","rate":0.2}],"prices":{"unit":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":null,"currency_code":"GBP"},"line_total":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":null,"currency_code":"GBP"},"currency_code":"GBP"}}],"shipping_details":[{"carrier_code":"UPS","carrier_service_code":"SV","method_name":"UPS Worldwide Saver","method_identifier":"UPSWorldwideSaver","prices":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"shipping_address":{"address":"[Object]","contact":"[Object]","display_name":null,"metadata":"[Object]","marketplaces":"[Object]","coordinates":"[Object]"}}],"payment_details":[{"payment_info":{"transaction_details":{"gateway":"stripe","reference":null,"token":"ch_3L8Qnd2eZvKYlo2C1SNDmEfL","high_risk":false,"method":{}},"card_details":{"last4":"5710","exp_month":8,"exp_year":2025,"country_code":"US","cardholder_name":"Jamie Foster","company":"Mastercard","bin":"400344"},"amount":4500,"currency_code":"USD"},"status":"succeeded","billing_address":{"address":"[Object]","contact":"[Object]","display_name":null,"metadata":"[Object]","marketplaces":"[Object]","coordinates":"[Object]"},"created_at":"2021-07-25T14:37:43.68Z","updated_at":"2021-07-25T14:37:43.68Z"}],"current_status":{"order":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"},"payment":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"},"fulfilment":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"}},"prices":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"refunds":[{"id":"re_2YlgkP2OGf8NpnA3CyOvpuo6W34","status":"refunded","description":"shipment arrived late to customer, goodwill refund.","amount":500,"currency_code":"GBP","created_at":"2022-05-02T20:00:35.476360Z","updated_at":"2022-05-02T20:00:35.476360Z"}],"on_hold":true,"hold_description":"string","alternative_identifiers":["RHRUESFBG9"]}'

Response

{
  "id": "ord_1HCpXwx2EK9oYluWbacgeCnFcLf",
  "customer": {
    "id": "cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"
  },
  "name": "#42196",
  "note": "Please leave the package in the parcel bin if I'm not home during delivery.",
  "marketplace": {
    "platform": "shopify",
    "id": "1073459966"
  },
  "metadata": {
    "hs_tariff_code": "1982740100"
  },
  "line_items": [
    {
      "id": "li_29U5Okdr6frqFyaa5wo6E9vWDma",
      "is_custom": false,
      "product": {
        "id": "prod_29U5Okw4MkbHiAkMg20Ukx8eKhj",
        "name": "SuperZap Microwave",
        "variant": {
          "id": "vrnt_29U5Ojl3byzXQ0Eotk3e1917t21",
          "name": "Black 3000W",
          "gtin": "84012345123452",
          "sku": "SZ-MIC-3000-B"
        }
      },
      "marketplace": {
        "platform": "shopify",
        "id": "1073459966"
      },
      "metadata": {
        "hs_tariff_code": "1982740100"
      },
      "shipping_detail": {
        "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP"
      },
      "quantity": 1,
      "shipping_required": true,
      "discounts": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "code": "30OFFTDC",
          "description": "30% Off - Trade Discount",
          "amount": 500,
          "currency_code": "GBP"
        }
      ],
      "tax_lines": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "name": "VAT (Standard 20%)",
          "type": "inclusive",
          "amount": 1200,
          "currency_code": "GBP",
          "rate": 0.2
        }
      ],
      "prices": {
        "unit": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "line_total": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "currency_code": "GBP"
      }
    }
  ],
  "committed_at": "2022-03-26T15:47:19Z",
  "shipping_details": [
    {
      "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
      "carrier_code": "UPS",
      "carrier_service_code": "SV",
      "method_name": "UPS Worldwide Saver",
      "method_identifier": "UPSWorldwideSaver",
      "prices": {
        "base": 42000,
        "discount": 35000,
        "tax": 35000,
        "subtotal": 7000,
        "total": 0.2,
        "tax_rates": {
          "additive": 0.18,
          "inclusive": 0.2,
          "blended": 0.38
        },
        "currency_code": "GBP"
      },
      "shipping_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      }
    }
  ],
  "payment_details": [
    {
      "id": "pd_2AJzG3TRewYEJMUwSCwv7VPtMZb",
      "payment_info": {
        "transaction_details": {
          "gateway": "stripe",
          "reference": null,
          "token": "ch_3L8Qnd2eZvKYlo2C1SNDmEfL",
          "high_risk": false,
          "method": {}
        },
        "card_details": {
          "last4": "5710",
          "exp_month": 8,
          "exp_year": 2025,
          "country_code": "US",
          "cardholder_name": "Jamie Foster",
          "company": "Mastercard",
          "bin": "400344"
        },
        "amount": 4500,
        "currency_code": "USD"
      },
      "status": "succeeded",
      "billing_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      },
      "created_at": "2021-07-25T14:37:43.68Z",
      "updated_at": "2021-07-25T14:37:43.68Z"
    }
  ],
  "current_status": {
    "order": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "payment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "fulfilment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    }
  },
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "refunds": [
    {
      "id": "re_2YlgkP2OGf8NpnA3CyOvpuo6W34",
      "status": "refunded",
      "description": "shipment arrived late to customer, goodwill refund.",
      "amount": 500,
      "currency_code": "GBP",
      "created_at": "2022-05-02T20:00:35.476360Z",
      "updated_at": "2022-05-02T20:00:35.476360Z"
    }
  ],
  "on_hold": true,
  "hold_description": "string",
  "alternative_identifiers": [
    "RHRUESFBG9"
  ]
}

undefined

GET/orders

Get Orders

Retrieve a list of orders for an organisation.

This endpoint is the primary means for retrieving orders, and provides a number of filters for retrieving orders by their properties, such as status, creation date, and so forth.

If one is search for orders, the Order Lookup endpoint exists for this use case.

If order IDs are passed that do not exist, the response will not include the requested orders, rather than failing outright.

As with other resources, this endpoint returns paginated results. The details of how pagination works can be found in the pagination article.

Query Parameters

  • Name
    cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request.

  • Name
    results
    Type
    integer
    Restrictions
    Description

    A number representing the maximum number of results that the request should return. A value with a minimum of 10 and a maximum of 100 is allowed. Any request for results outside this range will return the nearest bound.

  • Name
    min_date_created
    Type
    string(date-time)
    Restrictions
    Description

    Minimum date the order was created in RFC-3339 format.

  • Name
    max_date_created
    Type
    string(date-time)
    Restrictions
    Description

    Maximum date the order was created in RFC-3339 format.

  • Name
    min_date_updated
    Type
    string(date-time)
    Restrictions
    Description

    Minimum date the order was updated in RFC-3339 format.

  • Name
    max_date_updated
    Type
    string(date-time)
    Restrictions
    Description

    Maximum date the order was updated in RFC-3339 format.

  • Name
    customer_id
    Type
    string
    Restrictions
    Description

    The ID for a customer.

  • Name
    is_deleted
    Type
    boolean
    Restrictions
    Description

    Returns orders that have been deleted.

  • Name
    status
    Type
    string
    Restrictions
    Description

    Return orders with the specified status.

  • Name
    marketplace
    Type
    string
    Restrictions
    Description

    Return orders connected to the specified marketplace

  • Name
    sort
    Type
    string
    Restrictions
    Description

    The method by which results are sorted.

  • Name
    order_id
    Type
    array[string]
    Restrictions
    Description

    A repeatable parameter, each containing an order ID that should be retrieved.

  • Name
    status_log
    Type
    boolean
    Restrictions
    Description

    Whether the order response contains the full log of status codes, past and present.

Request

GET
/orders
curl --request GET \
--url https://api.envoy.one/orders \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "id": "ord_1HCpXwx2EK9oYluWbacgeCnFcLf",
      "customer": {
        "id": "cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"
      },
      "name": "#42196",
      "note": "Please leave the package in the parcel bin if I'm not home during delivery.",
      "marketplace": {
        "platform": "shopify",
        "id": "1073459966"
      },
      "metadata": {
        "hs_tariff_code": "1982740100"
      },
      "line_items": [
        {
          "id": "li_29U5Okdr6frqFyaa5wo6E9vWDma",
          "is_custom": false,
          "product": {
            "id": null,
            "name": null,
            "variant": null
          },
          "marketplace": {
            "platform": null,
            "id": null
          },
          "metadata": "[Object]",
          "shipping_detail": {
            "id": null
          },
          "quantity": 1,
          "shipping_required": true,
          "discounts": [
            "["
          ],
          "tax_lines": [
            "["
          ],
          "prices": {
            "unit": null,
            "line_total": null,
            "currency_code": null
          }
        }
      ],
      "committed_at": "2022-03-26T15:47:19Z",
      "shipping_details": [
        {
          "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
          "carrier_code": "UPS",
          "carrier_service_code": "SV",
          "method_name": "UPS Worldwide Saver",
          "method_identifier": "UPSWorldwideSaver",
          "prices": {
            "base": null,
            "discount": null,
            "tax": null,
            "subtotal": null,
            "total": null,
            "tax_rates": null,
            "currency_code": null
          },
          "shipping_address": null
        }
      ],
      "payment_details": [
        {
          "id": "pd_2AJzG3TRewYEJMUwSCwv7VPtMZb",
          "payment_info": {
            "transaction_details": null,
            "card_details": null,
            "amount": null,
            "currency_code": null
          },
          "status": "succeeded",
          "billing_address": null,
          "created_at": "2021-07-25T14:37:43.68Z",
          "updated_at": "2021-07-25T14:37:43.68Z"
        }
      ],
      "current_status": {
        "order": {
          "code": "ORDER_CONFIRMED",
          "description": "Payment received and order committed, order has been confirmed.",
          "created_at": "2022-06-16T18:40:22.717563"
        },
        "payment": {
          "code": "ORDER_CONFIRMED",
          "description": "Payment received and order committed, order has been confirmed.",
          "created_at": "2022-06-16T18:40:22.717563"
        },
        "fulfilment": {
          "code": "ORDER_CONFIRMED",
          "description": "Payment received and order committed, order has been confirmed.",
          "created_at": "2022-06-16T18:40:22.717563"
        }
      },
      "prices": {
        "base": 42000,
        "discount": 35000,
        "tax": 35000,
        "subtotal": 7000,
        "total": 0.2,
        "tax_rates": {
          "additive": 0.18,
          "inclusive": 0.2,
          "blended": 0.38
        },
        "currency_code": "GBP"
      },
      "refunds": [
        {
          "id": "re_2YlgkP2OGf8NpnA3CyOvpuo6W34",
          "status": "refunded",
          "description": "shipment arrived late to customer, goodwill refund.",
          "amount": 500,
          "currency_code": "GBP",
          "created_at": "2022-05-02T20:00:35.476360Z",
          "updated_at": "2022-05-02T20:00:35.476360Z"
        }
      ],
      "on_hold": true,
      "hold_description": "string",
      "alternative_identifiers": [
        "RHRUESFBG9"
      ]
    }
  ],
  "next_cursor": "WyIyMDIzLTAzLTIxVDAwOjM1OjU5LjczMDYyMVoiXQ==",
  "previous_cursor": "WyIyMDIzLTAzLTE5VDA0OjI4OjAxLjQ4NDg5WiJd",
  "limit": 20
}

undefined

GET/orders/{order_id}

Get Order

Retrieves an order by it's ID.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Query Parameters

  • Name
    status_log
    Type
    boolean
    Restrictions
    Description

    Whether the order response contains the full log of status codes, past and present.

Request

GET
/orders/{order_id}
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

PATCH/orders/{order_id}

Update Order

Updates an order by ID.

It is highly recommended that anyone looking to use the Orders API familiarises themself with the architecture and behaviour of the orders resource, as described in the article on orders.

Additionally, it is recommended that one familiarises oneself with the Create Order documentation, prior to using this endpoint, as it contains information on how the order resource works.

For orders that have been committed, restrictions on what can be updated apply. Please see the aforementioned article on orders for full details.

For resources such as shipping_details and payment_details, if any new entries are passed in the body of the request, they will be added to the order. If instead one wishes to update or delete existing resources, the dedicated endpoints should be used.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Query Parameters

  • Name
    status_log
    Type
    boolean
    Restrictions
    Description

    Whether the order response contains the full log of status codes, past and present.

Request

PATCH
/orders/{order_id}
curl --request PATCH \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"customer":{"id":"cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"},"name":"#42196","note":"Please leave the package in the parcel bin if I'\''m not home during delivery.","marketplace":{"platform":"shopify","id":"1073459966"},"metadata":{"hs_tariff_code":"1982740100"},"line_items":[{"is_custom":false,"product":{"id":"prod_29U5Okw4MkbHiAkMg20Ukx8eKhj","name":"SuperZap Microwave","variant":{"id":"vrnt_29U5Ojl3byzXQ0Eotk3e1917t21","name":"Black 3000W","gtin":"84012345123452","sku":"SZ-MIC-3000-B"}},"marketplace":{"platform":"shopify","id":"1073459966"},"metadata":{"hs_tariff_code":"1982740100"},"shipping_detail":{"id":"sd_2AINeixtljsn5YPYsmemIAUWGFP"},"quantity":1,"shipping_required":true,"discounts":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","code":"30OFFTDC","description":"30% Off - Trade Discount","amount":500,"currency_code":"GBP"}],"tax_lines":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","name":"VAT (Standard 20%)","type":"inclusive","amount":1200,"currency_code":"GBP","rate":0.2}],"prices":{"unit":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":null,"currency_code":"GBP"},"line_total":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":null,"currency_code":"GBP"},"currency_code":"GBP"}}],"shipping_details":[{"carrier_code":"UPS","carrier_service_code":"SV","method_name":"UPS Worldwide Saver","method_identifier":"UPSWorldwideSaver","prices":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"shipping_address":{"address":"[Object]","contact":"[Object]","display_name":null,"metadata":"[Object]","marketplaces":"[Object]","coordinates":"[Object]"}}],"payment_details":[{"payment_info":{"transaction_details":{"gateway":"stripe","reference":null,"token":"ch_3L8Qnd2eZvKYlo2C1SNDmEfL","high_risk":false,"method":{}},"card_details":{"last4":"5710","exp_month":8,"exp_year":2025,"country_code":"US","cardholder_name":"Jamie Foster","company":"Mastercard","bin":"400344"},"amount":4500,"currency_code":"USD"},"status":"succeeded","billing_address":{"address":"[Object]","contact":"[Object]","display_name":null,"metadata":"[Object]","marketplaces":"[Object]","coordinates":"[Object]"},"created_at":"2021-07-25T14:37:43.68Z","updated_at":"2021-07-25T14:37:43.68Z"}],"current_status":{"order":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"},"payment":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"},"fulfilment":{"code":"ORDER_CONFIRMED","description":"Payment received and order committed, order has been confirmed.","created_at":"2022-06-16T18:40:22.717563"}},"prices":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"refunds":[{"id":"re_2YlgkP2OGf8NpnA3CyOvpuo6W34","status":"refunded","description":"shipment arrived late to customer, goodwill refund.","amount":500,"currency_code":"GBP","created_at":"2022-05-02T20:00:35.476360Z","updated_at":"2022-05-02T20:00:35.476360Z"}],"on_hold":true,"hold_description":"string","alternative_identifiers":["RHRUESFBG9"]}'

Response

{
  "id": "ord_1HCpXwx2EK9oYluWbacgeCnFcLf",
  "customer": {
    "id": "cus_28ciEisyBRsQZ2jBMIrrpIrJFqh"
  },
  "name": "#42196",
  "note": "Please leave the package in the parcel bin if I'm not home during delivery.",
  "marketplace": {
    "platform": "shopify",
    "id": "1073459966"
  },
  "metadata": {
    "hs_tariff_code": "1982740100"
  },
  "line_items": [
    {
      "id": "li_29U5Okdr6frqFyaa5wo6E9vWDma",
      "is_custom": false,
      "product": {
        "id": "prod_29U5Okw4MkbHiAkMg20Ukx8eKhj",
        "name": "SuperZap Microwave",
        "variant": {
          "id": "vrnt_29U5Ojl3byzXQ0Eotk3e1917t21",
          "name": "Black 3000W",
          "gtin": "84012345123452",
          "sku": "SZ-MIC-3000-B"
        }
      },
      "marketplace": {
        "platform": "shopify",
        "id": "1073459966"
      },
      "metadata": {
        "hs_tariff_code": "1982740100"
      },
      "shipping_detail": {
        "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP"
      },
      "quantity": 1,
      "shipping_required": true,
      "discounts": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "code": "30OFFTDC",
          "description": "30% Off - Trade Discount",
          "amount": 500,
          "currency_code": "GBP"
        }
      ],
      "tax_lines": [
        {
          "id": "dc_2YjvVA5VFaSBaJDFSjvpncDYDIF",
          "name": "VAT (Standard 20%)",
          "type": "inclusive",
          "amount": 1200,
          "currency_code": "GBP",
          "rate": 0.2
        }
      ],
      "prices": {
        "unit": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "line_total": {
          "base": 42000,
          "discount": 35000,
          "tax": 35000,
          "subtotal": 7000,
          "total": 0.2,
          "tax_rates": null,
          "currency_code": "GBP"
        },
        "currency_code": "GBP"
      }
    }
  ],
  "committed_at": "2022-03-26T15:47:19Z",
  "shipping_details": [
    {
      "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
      "carrier_code": "UPS",
      "carrier_service_code": "SV",
      "method_name": "UPS Worldwide Saver",
      "method_identifier": "UPSWorldwideSaver",
      "prices": {
        "base": 42000,
        "discount": 35000,
        "tax": 35000,
        "subtotal": 7000,
        "total": 0.2,
        "tax_rates": {
          "additive": 0.18,
          "inclusive": 0.2,
          "blended": 0.38
        },
        "currency_code": "GBP"
      },
      "shipping_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      }
    }
  ],
  "payment_details": [
    {
      "id": "pd_2AJzG3TRewYEJMUwSCwv7VPtMZb",
      "payment_info": {
        "transaction_details": {
          "gateway": "stripe",
          "reference": null,
          "token": "ch_3L8Qnd2eZvKYlo2C1SNDmEfL",
          "high_risk": false,
          "method": {}
        },
        "card_details": {
          "last4": "5710",
          "exp_month": 8,
          "exp_year": 2025,
          "country_code": "US",
          "cardholder_name": "Jamie Foster",
          "company": "Mastercard",
          "bin": "400344"
        },
        "amount": 4500,
        "currency_code": "USD"
      },
      "status": "succeeded",
      "billing_address": {
        "address": "[Object]",
        "contact": "[Object]",
        "display_name": null,
        "metadata": "[Object]",
        "marketplaces": "[Object]",
        "coordinates": "[Object]",
        "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
      },
      "created_at": "2021-07-25T14:37:43.68Z",
      "updated_at": "2021-07-25T14:37:43.68Z"
    }
  ],
  "current_status": {
    "order": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "payment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    },
    "fulfilment": {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    }
  },
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "refunds": [
    {
      "id": "re_2YlgkP2OGf8NpnA3CyOvpuo6W34",
      "status": "refunded",
      "description": "shipment arrived late to customer, goodwill refund.",
      "amount": 500,
      "currency_code": "GBP",
      "created_at": "2022-05-02T20:00:35.476360Z",
      "updated_at": "2022-05-02T20:00:35.476360Z"
    }
  ],
  "on_hold": true,
  "hold_description": "string",
  "alternative_identifiers": [
    "RHRUESFBG9"
  ]
}

undefined

DELETE/orders/{order_id}

Delete Order

Deletes an order by ID

Deleting an order may only occur under certain circumstances:

  • The order must not have any fulfilments.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

DELETE
/orders/{order_id}
curl --request DELETE \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

POST/orders/{order_id}/commit

Commit Order

Commits the specified order.

Once an order has been committed, it cannot be uncommitted. Full details of the order architecture and the difference between uncommitted and committed orders are available in the Orders article.

Before shipments can be created, an order must be in the committed state.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

POST
/orders/{order_id}/commit
curl --request POST \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/commit \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

GET/orders/{order_id}/line_items

Get Order Line Items

Retrieves all the line items for a specified order.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

GET
/orders/{order_id}/line_items
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/line_items \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

POST/orders/{order_id}/line_items

Create Order Line Item

Add a line item to the specified order.

Line items are each assigned a unique ID when they are created, as products/product variant ID combinations are not guaranteed to be unique within a given order.

This stems from the fact that we need to support duplicate line items due to the way several ecommerce platforms handle customised products - often the product customisations are stored as line item metadata.

For example, a message for a laser engraved product might be stored in the laser_message metadata key. If a customer orders two of that product, but with a different message on each, this is represented as two line items for the same product, but each with the respective messages.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

POST
/orders/{order_id}/line_items
curl --request POST \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/line_items \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"is_custom":false,"product":{"id":"prod_29U5Okw4MkbHiAkMg20Ukx8eKhj","name":"SuperZap Microwave","variant":{"id":"vrnt_29U5Ojl3byzXQ0Eotk3e1917t21","name":"Black 3000W","gtin":"84012345123452","sku":"SZ-MIC-3000-B"}},"marketplace":{"platform":"shopify","id":"1073459966"},"metadata":{"hs_tariff_code":"1982740100"},"shipping_detail":{"id":"sd_2AINeixtljsn5YPYsmemIAUWGFP"},"quantity":1,"shipping_required":true,"discounts":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","code":"30OFFTDC","description":"30% Off - Trade Discount","amount":500,"currency_code":"GBP"}],"tax_lines":[{"id":"dc_2YjvVA5VFaSBaJDFSjvpncDYDIF","name":"VAT (Standard 20%)","type":"inclusive","amount":1200,"currency_code":"GBP","rate":0.2}],"prices":{"unit":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"line_total":{"base":42000,"discount":35000,"tax":35000,"subtotal":7000,"total":0.2,"tax_rates":{"additive":0.18,"inclusive":0.2,"blended":0.38},"currency_code":"GBP"},"currency_code":"GBP"}}'

undefined

GET/orders/{order_id}/payment_details

Get Order Payment Details

Retrieves all the payment details for a specified order.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

GET
/orders/{order_id}/payment_details
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/payment_details \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

POST/orders/{order_id}/payment_details

Create Order Payment Detail

Creates a payment detail for the specified order.

No payment processing occurs when creating an order payment detail. Whilst support for payment processing is on the roadmap, order payment details act as a record of payment, and transaction processing will happen in a separate endpoint.

As described in the Create Order endpoint, when creating a payment detail, external resources can be referenced by their ID, and will be populated server side. This applies to the following fields:

  • billing_address: Providing the id parameter with the ID for an address (prefix addr), will result in the stored address being used to populate the address information by default.
    It should be noted that the address must belong to the customer associated with the order. Attempting to use an address not associated with the customer will fail.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

POST
/orders/{order_id}/payment_details
curl --request POST \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/payment_details \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"payment_info":{"transaction_details":{"gateway":"stripe","reference":null,"token":"ch_3L8Qnd2eZvKYlo2C1SNDmEfL","high_risk":false,"method":{"type":"card","token":"pm_1L6ZIF2eZvKYlo2Cn6OzyDVs"}},"card_details":{"last4":"5710","exp_month":8,"exp_year":2025,"country_code":"US","cardholder_name":"Jamie Foster","company":"Mastercard","bin":"400344"},"amount":4500,"currency_code":"USD"},"status":"succeeded","billing_address":{"address":{"line_1":"29 Holgate Rd","line_2":"Segwick Street","line_3":"Kelvedon","city":"RACKWICK","province":"Cambershire","post_code":"KW16 2PE","country_code":"GB"},"contact":{"name":"Francesca Brady","company":"Malvinex Corp"},"display_name":null,"metadata":{"contact_email":"[email protected]"},"marketplaces":{"shopify":"657847832011"},"coordinates":{"latitude":51.5134297,"longitude":-0.103145,"confidence":1}},"created_at":"2021-07-25T14:37:43.68Z","updated_at":"2021-07-25T14:37:43.68Z"}'

undefined

PATCH/orders/{order_id}/payment_details/{payment_detail_id}

Update Order Payment Detail

Update a payment detail by ID for the specified order.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    payment_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order payment detail.

Request

PATCH
/orders/{order_id}/payment_details/{payment_detail_id}
curl --request PATCH \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/payment_details/pd_2ALbVHVIKmwBNZ5os13TlaFQvpl \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
  "carrier_code": "UPS",
  "carrier_service_code": "SV",
  "method_name": "UPS Worldwide Saver",
  "method_identifier": "UPSWorldwideSaver",
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "shipping_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  }
}

undefined

GET/orders/{order_id}/payment_details/{payment_detail_id}

Get Order Payment Detail

Retrieve an order payment detail by ID.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    payment_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order payment detail.

Request

GET
/orders/{order_id}/payment_details/{payment_detail_id}
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/payment_details/pd_2ALbVHVIKmwBNZ5os13TlaFQvpl \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
  "carrier_code": "UPS",
  "carrier_service_code": "SV",
  "method_name": "UPS Worldwide Saver",
  "method_identifier": "UPSWorldwideSaver",
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "shipping_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  }
}

undefined

DELETE/orders/{order_id}/payment_details/{payment_detail_id}

Delete Order Payment Detail

Deletes a payment detail with the specified ID.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    payment_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order payment detail.

Request

DELETE
/orders/{order_id}/payment_details/{payment_detail_id}
curl --request DELETE \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/payment_details/pd_2ALbVHVIKmwBNZ5os13TlaFQvpl \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{}

undefined

GET/orders/{order_id}/shipping_details

Get Order Shipping Details

Retrieves a list of shipping details associated with an order.

Shipping details are a seperate resource from shipments - the former contains details of the shipping information and costs displayed to the customer, whereas the latter holds the shipment information for the actual fulfilments associated with an order.

An important point to note is that the costs detailed in the shipping details are not in any way linked to the shipment costs - it is up to the client to charge the customer appropriately for shipping, with the price that they pay being reflected in the shipping detail. The costs that the merchant pays for the shipment of the order are reflected in the shipment resource.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

GET
/orders/{order_id}/shipping_details
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/shipping_details \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

POST/orders/{order_id}/shipping_details

Create Order Shipping Detail

Creates a new shipping detail for a specified order.

As mentioned in the Get Order Shipping Details endpoint, this resource relates to customer-facing shipping costs and information, and not the shipment information from fulfilments.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

POST
/orders/{order_id}/shipping_details
curl --request POST \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/shipping_details \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

PATCH/orders/{order_id}/shipping_details/{shipping_detail_id}

Update Order Shipping Detail

Update a shipping detail by ID for the specified order.

If the request includes any updates to the shipping address, the updates will be made directly against the order address instance. This will affect any other resources also referencing the order address.

In the event that there are any in progress or complete fulfilments and corresponding shipments, shipments where the label has already been generated will not automatically be updated with new details. It will be necessary to delete the label and recreate it, at which point the updated shipping details will be used.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    shipping_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order shipping detail.

Request

PATCH
/orders/{order_id}/shipping_details/{shipping_detail_id}
curl --request PATCH \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/shipping_details/sd_2AINRz5f6zhe4i7kui9zxD7rPw0 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
  "carrier_code": "UPS",
  "carrier_service_code": "SV",
  "method_name": "UPS Worldwide Saver",
  "method_identifier": "UPSWorldwideSaver",
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "shipping_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  }
}

undefined

GET/orders/{order_id}/shipping_details/{shipping_detail_id}

Get Order Shipping Detail

Retrieve an order shipping detail by ID.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    shipping_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order shipping detail.

Request

GET
/orders/{order_id}/shipping_details/{shipping_detail_id}
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/shipping_details/sd_2AINRz5f6zhe4i7kui9zxD7rPw0 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "sd_2AINeixtljsn5YPYsmemIAUWGFP",
  "carrier_code": "UPS",
  "carrier_service_code": "SV",
  "method_name": "UPS Worldwide Saver",
  "method_identifier": "UPSWorldwideSaver",
  "prices": {
    "base": 42000,
    "discount": 35000,
    "tax": 35000,
    "subtotal": 7000,
    "total": 0.2,
    "tax_rates": {
      "additive": 0.18,
      "inclusive": 0.2,
      "blended": 0.38
    },
    "currency_code": "GBP"
  },
  "shipping_address": {
    "address": {
      "line_1": "29 Holgate Rd",
      "line_2": "Segwick Street",
      "line_3": "Kelvedon",
      "city": "RACKWICK",
      "province": "Cambershire",
      "post_code": "KW16 2PE",
      "country_code": "GB"
    },
    "contact": {
      "name": "Francesca Brady",
      "company": "Malvinex Corp"
    },
    "display_name": null,
    "metadata": {
      "contact_email": "[email protected]"
    },
    "marketplaces": {
      "shopify": "657847832011"
    },
    "coordinates": {
      "latitude": 51.5134297,
      "longitude": -0.103145,
      "confidence": 1
    },
    "id": "oa_2A7gLg26ZNyUtsviRTBYlZRDvvU"
  }
}

undefined

DELETE/orders/{order_id}/shipping_details/{shipping_detail_id}

Delete Order Shipping Detail

Deletes a shipping detail with the specified ID.

When a shipping detail is deleted, any line items that are assigned to the shipping detail will be deassociated with the shipping details. These items will need to be manually reassigned to an alternative shipping detail.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

  • Name
    shipping_detail_id
    Type
    string
    Restrictions
    Description

    The unique ID for the order shipping detail.

Request

DELETE
/orders/{order_id}/shipping_details/{shipping_detail_id}
curl --request DELETE \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/shipping_details/sd_2AINRz5f6zhe4i7kui9zxD7rPw0 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{}

undefined

GET/orders/{order_id}/status

Get Order Status

Retrieves the order status events for a specific order.

The order status feed is an append only event stream associated with an order. Whilst it is possible for the order state to change to one that occurred before (eg. to go from fulfilled to unfulfilled), the previous event will not be deleted. This is for traceability purposes.

The order status cannot be manually edited - it is updated depending on certain events occurring.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

GET
/orders/{order_id}/status
curl --request GET \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/status \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "code": "ORDER_CONFIRMED",
      "description": "Payment received and order committed, order has been confirmed.",
      "created_at": "2022-06-16T18:40:22.717563"
    }
  ]
}

undefined

POST/orders/{order_id}/status

Add Order Status

Adds a new status to the specified order.

This endpoint is currently unpublished, and is used by internal services to update the order status when certain events happen, eg. ORDER_FULFILLED when a fulfilment is completed.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The unique ID for an order.

Request

POST
/orders/{order_id}/status
curl --request POST \
--url https://api.envoy.one/orders/ord_2A4oPn2mvjq4omXGxb0cgSnXa7o/status \
--header 'Authorization: Bearer {access-token}'

undefined