Sign in

v1

latestOpenAPI 3.0.12026-07-243902.3 MB
Orders

Create an Order

This endpoint creates a representation of an order in Extend’s system. Orders should represent the complete order as processed through a merchant’s store, including line details that enable Extend to determine how to process each line.

Orders will require at least one order line item to be created. Extend will automatically categorize each order line item based on the information that is sent with it. The four line item types are:

  • Contract
    • Determined by receiving a Product and a Plan ID
    • Will trigger creation of a product protection contract
  • Lead
    • Determined by receiving a warrantable Product without a Plan ID
    • Will trigger creation of a lead token
  • Shipping Protection Contract
    • Determined by receiving Shipment Info and a Quote ID
    • Will trigger creation of a shipping protection contract
  • Non-Warrantable
    • determined by receiving a non-warrantable product

Orders created after items have been received by the customer and sent with a fulfilled status will immediately trigger contract creation. Orders can also be created at the time of purchase with line items sent in an unfulfilled status and subsequently updated to fulfill line items triggering contract creation once the customers receive the product.

Important

Order Line Items should include all items purchased on the order regardless of contract status.

post/orders

Request body

cartIdstring
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
storeIdstring required

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

transactionIdstring required

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

discountAmountTotalinteger

Total discount amount for the order.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

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.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

customerReturnPolicyIdstring

Unique identifier for the return policy associated with this order.

shippingCostTotalinteger

The total shipping cost for the order.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

shippingTaxCostTotalinteger

Total shipping tax amount for the order.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

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

The state of the order in Extend DB (needed for auditing).<p>Note - When line items are fulfilled, the product protection contract is created. By default, line items will be set to a fulfilled status if the field or no field value is provided in the request.</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>

storeNamestring

Merchant's store name in Extend.

taxCostTotalinteger

The total tax cost for the order.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

totalinteger

Total amount paid for entire order.<p>Amount should be expressed in terms of the smallest currency unit.</p> <ul> <li>$19.99 would be 1999</li> <li>1.234,56 € would be 123456</li> <li>£ 1,999.99 would be 199999</li> </ul>

transactionDateinteger

Transaction date when customer placed order (13 digit timestamp).

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

{
  "cartId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "storeId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "transactionId": "c57ed096-24ef-49a4-a20a-d1b8bf770980",
  "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"
    }
  ],
  "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",
  "shippingTaxCostTotal": 137,
  "storeName": "Bright Jewelers",
  "taxCostTotal": 1299,
  "total": 5999,
  "transactionDate": 1668561247000,
  "waitPeriod": 2,
  "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"
  },
  "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"
    }
  }
}

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