Sign in

v1

latestOpenAPI 3.0.12026-07-243902.3 MB
Orders

Create / Update an Order

This endpoint allows merchants to create a new order or update an existing order. New orders will be created if the Transaction ID value provided does not already exist on an order for the merchant’s store. If the Transaction ID value provided exists on an order for the merchant’s store, updates will be made according to the data included in the API request.

Please find instructions below on how to perform certain updates on existing orders:

  • To refund all contracts associated to an order, include the order status of 'refunded' in the request. This will refund all contract line items and cancel any line items that are not associated to a contract.
  • To refund or cancel line items on an order, either send a reduced quantity for the line item or do not include the line item in the request. This will refund all contracts for the line item or cancel the line item if it is not associated to a contract.
  • To refund a single product protection contract only on an order, do not include a plan container with the line item that corresponds to the contract that needs to be refunded.
  • To add line items to an order, increment the quantity of the existing line or include a new line item with a unique Line Item Transaction ID in the request.
  • To maintain an accurate number of fulfilled products on order line items, always send the correct value of fulfilled products in Fulfilled Quantity field in the request.
  • To maintain shipment records on orders, our service will use the Tracking ID in each record to determine if shipments should be added, updated, or removed from the order.
  • When line items that are covered by a shipping protection contract are canceled or refunded, our system will automatically attempt to issue a partial refund for the contract. The API response will display products that were removed from coverage and the new contract premium if the partial refund is processed successfully.
put/orders

Request body

cartIdstring

Unique identifier for the cart in the merchant’s system.

currency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' required
discountAmountTotalinteger

Total discount amount for the order.

formIdstring

This field is used for Jewelry orders where merchants need to provide additional reporting and analytics context for the order.

isHistoricalboolean

Denotes whether or not the order was created through the historical orders endpoint.

isTestboolean

Flag that tracks whether the transaction was created as a test or not. NOTE - This is defaulted to false and should be used only under special circumstances.

merchantCustomerIdstring

Unique identifier for the customer in the merchant’s system.

poNumberstring

Purchase order number in merchant's system.

productCostTotalinteger

Total purchase cost of all products (and their quantities) included on the order, not including shipping, tax, or discount amounts.

customerReturnPolicyIdstring

Unique identifier for the return policy associated with this order.

shippingCostTotalinteger

The total shipping cost for the order.

shippingTaxCostTotalinteger

Total shipping tax amount for the order.

status'pending' | 'open' | 'voided' | 'closed' | 'canceled' | 'refunded'

Status of the order in Extend’s system. Note - A status of refunded can be included in the request to indicate the entire order has been refunded. This is only available in the Orders Upsert endpoint.

storeIdstring required

Unique identifier for merchant’s store in Extend’s system.

storeNamestring

Merchant's store name in Extend.

taxCostTotalinteger

The total tax cost for the order.

totalinteger

Total cost of the order, including all product purchase costs, shipping, taxes, discounts, and any other amounts. This should reflect the total amount that the customer paid for the order.

transactionDateinteger

Order’s transaction date. No default will be set if no value is provided.

transactionIdstring required

Unique identifier provided by merchant for transaction associated to Extend order.

waitPeriodnumber

Number of days that should be applied before a contract is created from an order. This is typically used to confirm a payment was successfully captured or to wait a period of time to ensure a transaction isn’t fraudulent. NOTE - This field accepts the number of days and does not have to be a whole number (e.g. half a day can be sent as 0.5).

Example request

{
  "analytics": {
    "contractPlanCategory": "Service Contract",
    "customerStatus": "existing",
    "customerType": "Consumer",
    "discountSource": "Email promo",
    "loyaltyStatus": "elite",
    "paymentMethod": "Credit",
    "paymentInstrument": "Visa",
    "marketingOptIn": true
  },
  "discounts": [
    {
      "discountCode": "WELCOME20",
      "discountType": "percentage",
      "amountValue": 20,
      "description": "One-time welcome 20% off entire order discount"
    }
  ],
  "cartId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "customer": {
    "billingAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    },
    "email": "customer@gmail.com",
    "name": "John Smith",
    "locale": "en-us",
    "loyaltyStatus": "member",
    "phone": "123-456-7890",
    "region": "US",
    "shippingAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    },
    "subdivision": "CA"
  },
  "discountAmountTotal": 430,
  "formId": "12cyx",
  "isHistorical": true,
  "merchantCustomerId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "poNumber": "PO1403X9",
  "productCostTotal": 19000,
  "resellerMerchant": {
    "id": "154ebea0-6c1b-46a4-b166-032246330526",
    "name": "Acme Reseller Company",
    "domain": "https://acme.reseller.com"
  },
  "customerReturnPolicyId": "123e4567-e89b-12d3-a456-426614174000",
  "saleOrigin": {
    "agentId": "sales agent",
    "channel": "web",
    "integratorId": "vs03jskavj",
    "locationId": "Store #123",
    "platform": "BigCommerce",
    "storeAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    }
  },
  "shippingTaxCostTotal": 137,
  "storeId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "storeName": "Bright Jewelers",
  "taxCostTotal": 1299,
  "total": 5999,
  "transactionDate": 1668561247000,
  "transactionId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "waitPeriod": 2
}

Response

Successful creation of the order.

cartIdstring

Unique identifier for the cart in the merchant’s system.

currency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' required
createdAtinteger

Date the order was created (generated by Extend).

discountAmountTotalinteger

Total discount amount for the order.

formIdstring

This field is used for Jewelry orders where merchants need to provide additional reporting and analytics context for the order.

idstring required

Unique ID used to identify the Extend order.

consumerProfileIdstring

The consumer profile ID associated with the order.

isTestboolean

Flag that tracks whether the transaction was created as a test or not. NOTE - This is defaulted to false and should be used only under special circumstances.

merchantCustomerIdstring

Unique identifier for the customer in the merchant’s system.

parentReferenceIdstring

The parent reference ID of the order.

poNumberstring

Purchase order number in merchant's system.

productCostTotalinteger

Total purchase cost of all products (and their quantities) included on the order, not including shipping, tax, or discount amounts.

refundedAtinteger

Date the order was refunded (generated by Extend).

customerReturnPolicyIdstring

Unique identifier for the return policy associated with this order.

shippingCostTotalinteger

The total shipping cost for the order.

shippingTaxCostTotalinteger

Total shipping tax amount for the order.

status'pending' | 'open' | 'voided' | 'closed' | 'canceled' | 'refunded' | 'inactive' required
<p>Status of the order in Extend’s system.</p><ul><li><strong>pending</strong> - Order has been created with a wait period value. This is typically used to create an order that requires a certain time period to pass before it is considered a valid order.</li><li><strong>open</strong> - Order has been created with at least one order line item that has not been fulfilled</li><li><strong>voided</strong> - Order was voided due to circumstances that indicate the order was not valid when it was first created. This can be due to a fraudulent order.</li><li><strong>closed</strong> - Order was successfully processed with all order line items fulfilled.</li><li><strong>canceled</strong> - Order was canceled or refunded at the request of a customer or the merchant.</li></ul>
storeIdstring required

Unique identifier for merchant’s store in Extend’s system.

storeNamestring required

Merchant's store name in Extend.

taxCostTotalinteger

The total tax cost for the order.

totalinteger

Total amount paid for entire order.

transactionDateinteger

Order's transaction date. No default will be set if no value is provided.

transactionIdstring required

Merchant supplied unique transaction identifier, which may be used for querying.

updatedAtinteger

Extend-generated timestamp indicating the last update performed.

waitPeriodnumber

Number of days that should be applied before a contract is created from an order. This is typically used to confirm a payment was successfully captured or to wait a period of time to ensure a transaction isn't fraudulent. NOTE - This field accepts the number of days and does not have to be a whole number (e.g. half a day can be sent as 0.5).

Example response

{
  "analytics": {
    "contractPlanCategory": "Service Contract",
    "customerStatus": "existing",
    "customerType": "Consumer",
    "discountSource": "Email promo",
    "loyaltyStatus": "elite",
    "paymentMethod": "Credit",
    "paymentInstrument": "Visa",
    "marketingOptIn": true
  },
  "discounts": [
    {
      "discountCode": "WELCOME20",
      "discountType": "percentage",
      "amountValue": 20,
      "description": "One-time welcome 20% off entire order discount"
    }
  ],
  "cartId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "createdAt": 1557267465,
  "customer": {
    "billingAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    },
    "email": "customer@gmail.com",
    "name": "John Smith",
    "locale": "en-us",
    "loyaltyStatus": "member",
    "phone": "123-456-7890",
    "region": "US",
    "shippingAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    },
    "subdivision": "CA"
  },
  "discountAmountTotal": 430,
  "formId": "12cyx",
  "id": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "consumerProfileId": "c57ed096-24ef-49a4-a20a-d1b8bf770981",
  "lineItems": [
    {
      "contractId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
      "lineItemTransactionId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
      "offerId": "7cdabc72-227d-8f76-a9e7-c91de35c2781",
      "offerPlanId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
      "plan": {
        "id": "10001-misc-elec-adh-replace-1y",
        "purchasePrice": 1999,
        "termsId": "12A",
        "termsVersion": "2",
        "version": "2"
      },
      "product": {
        "deliveryStatus": "shipped",
        "id": "SKU-123-456",
        "purchasePrice": 1999,
        "serialNumber": "123SAD3",
        "purchaseDate": 1652403703000,
        "listPrice": 1999,
        "name": "Shiny Hat 2",
        "mfrWarranty": {
          "url": "https://www.manufacturer.com/warranty"
        },
        "parentReferenceId": "550e8400-e29b-41d4-a716-446655440000"
      },
      "leadToken": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
      "id": "3f87b162-3462-4c0c-bb9c-af2b14e025c3",
      "accountId": "3f87b162-3462-4c0c-bb9c-af2b14e025c3",
      "status": "fulfilled",
      "storeId": "3f87b162-3462-4c0c-bb9c-af2b14e025c3",
      "orderId": "3f87b162-3462-4c0c-bb9c-af2b14e025c3",
      "transactionId": "3f87b162-3462-4c0c-bb9c-af2b14e025c3",
      "isProductWarrantabilityVerified": true,
      "fulfilledAt": 1652402394000,
      "refundedAt": 1652402394000,
      "cancelledAt": 1652402394000,
      "createdAt": 1652402394000,
      "updatedAt": 1652402394000,
      "discountAmount": 399,
      "taxCost": 199,
      "adjustments": {
        "calculatedListPrice": 5999,
        "originalPlanId": "3f87b162-3462-4c0c-bb9c-af2b14e025c3"
      },
      "contractFailedReasons": [
        "Contract line requested more coverage than available quantities on the order for at least one product"
      ],
      "analytics": {
        "fulfillmentMethod": "BOPIS"
      }
    }
  ],
  "merchantCustomerId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "parentReferenceId": "550e8400-e29b-41d4-a716-446655440000",
  "poNumber": "PO1403X9",
  "productCostTotal": 19000,
  "refundedAt": 1557267465,
  "resellerMerchant": {
    "id": "154ebea0-6c1b-46a4-b166-032246330526",
    "name": "Acme Reseller Company",
    "domain": "https://acme.reseller.com"
  },
  "customerReturnPolicyId": "123e4567-e89b-12d3-a456-426614174000",
  "saleOrigin": {
    "agentId": "sales agent",
    "channel": "web",
    "integratorId": "vs03jskavj",
    "locationId": "Store #123",
    "platform": "BigCommerce",
    "storeAddress": {
      "address1": "535 Mission Street",
      "address2": "11th Floor",
      "city": "San Francisco",
      "countryCode": "US",
      "postalCode": "94526",
      "province": "CA"
    }
  },
  "shippingCostTotal": 1999,
  "shippingTaxCostTotal": 137,
  "status": "closed",
  "storeId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "storeName": "Bright Jewelers",
  "taxCostTotal": 1299,
  "total": 5999,
  "transactionDate": 1668561247000,
  "transactionId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "updatedAt": 1557267465,
  "waitPeriod": 2,
  "coveredProducts": [
    {
      "lineItemTransactionId": "07746dc6-53c2-4278-8ba8-0d8905150409"
    }
  ]
}