Sign in

v1

latestOpenAPI 3.0.12026-07-243902.3 MB
Orders

Batch Create Historical Orders

This endpoint is used to batch create orders or batch create historical orders. NOTE - For normal or historical orders, this endpoint currently only supports creating 10 orders with each request.

“Historical“ orders are defined as orders that were created in a merchant’s store before partnering with Extend to sell protection plans. Historical orders currently support the creation of historical leads, which are simply leads that need to be created on historical orders. A default “wait period“ of 14 days will be used for all orders created to allow for products to be set up properly as warrantable, as needed, prior to creating leads from the orders.

The primary purpose of historical leads is to help merchants generate additional revenue on orders where customers purchased products that they are still eligible to protect under an extended warranty contract.

Please note, it is important that the merchant’s Extend store has products configured as warrantable before creating historical orders. If there are a significant number of products that are not mapped to protection plans, the order line item will be consider non-warrantable, preventing a lead to be successfully created.

This endpoint now supports handling existing orders in Extend’s system when creating historical orders. If a Transaction ID is provided in this request body and the Transaction ID exists on another order, Extend’s system will attempt to generate new line items for any potential historical leads. If our system determines the line item already exists and a historical lead cannot or should not be created on the existing order, the order line item will be skipped.

post/orders/batch?historical

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 batch creation of Orders

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