Contents x
    Order Import Format
    • 31 May 2024
    • 11 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Contents

    Order Import Format

    • Updated on 31 May 2024
    • 11 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Article summary

    This section describes how to provide order data to the import service.

    {
  "$ref": "#/definitions/orderSchema",
  "definitions": {
    "orderSchema": {
      "type": "object",
      "properties": {
        "orders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "delegateId": {
                "type": "string",
                "minLength": 1,
                "description": "A unique identifier for ther order, used to ensure the same order is never accidentally re-created as a duplicate."
              },
              "customerId": {
                "type": "string",
                "minLength": 1,
                "description": "The unique identifier for the customer used in the database or customers import"
              },
              "productChoices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "productId": {
                      "type": "string",
                      "minLength": 1,
                      "description": "A unique identifier for each product which must match the IDs in the provided Products import or the database"
                    },
                    "quantity": {
                      "type": "number",
                      "minimum": 1,
                      "description": "Records how many of each product were delivered in that order."
                    }
                  },
                  "required": ["productId", "quantity"],
                  "additionalProperties": false
                },
                "minItems": 1
              },
              "boxNumber": {
                "type": "number",
                "minimum": 1,
                "description": "The order ordinal, aka how many committed orders a customer has had so far, recording what total box number a customer is on as part of their subscription, regardless of subscription type. This should increment with refunded but not cancelled orders. A contract may not have multiple committed orders with the same box number."
              },
              "subscriptionTypeBoxNumber": {
                "type": "number",
                "minimum": 1,
                "description": "The position the user has reached in their subscription type, e.g. for playlists. Often the same as the boxNumber."
              },
              "contractId": {
                "type": "string",
                "minLength": 1,
                "description": "The id of the subscription associated with the order. This must match a subscription provided in the subscriptionContracts data or will be skipped."
              },
              "deliveryDate": {
                "type": "string",
                "format": "date",
                "description": "Tthe date the order was delivered on, in ISO 8601 format YYYY-MM-DD."
              },
              "price": {
                "type": "number",
                "minimum": 0,
                "multipleOf": 0.01,
                "description": "The price the customer paid (or was scheduled to pay until the order was cancelled) to receive the order, including any promotions, in the currency's normal units, e.g. £10.30"
              },
              "promoCode": {
                "anyOf": [
                  {
                    "anyOf": [
                      {
                        "not": {}
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The discount code used on an order. Optional, given not all orders will have a discount applied."
              },
              "subscriptionTypeId": {
                "type": "string",
                "minLength": 1,
                "description": "An identifier for the subscription type a given order was part of, matching a subscription type in the subscriptionTypes import, if using - otherwise this value will be replaced with the matching subscription contract's subscription type id."
              },
              "subscriptionPhaseId": {
                "type": "string",
                "minLength": 1,
                "description": "The id of a subscription phase matching one in the subscription contracts import."
              },
              "state": {
                "type": "string",
                "enum": ["committed", "cancelled"],
                "description": "The status of the order. An order should be be committed if it was billed/delivered successfully, even if it was later refunded. Status \"cancelled\" should be used for orders that were never billed or failed to bill."
              },
              "whenCommitted": {
                "type": "string",
                "format": "date",
                "description": "The date the order was committed, if applicable."
              },
              "cancellationReason": {
                "type": "string",
                "description": "The reason for cancelling the order, if applicable."
              },
              "billingStatus": {
                "type": "string",
                "enum": ["SUCCEEDED", "DELEGATED", "FAILED", "NOT BILLED", "REFUNDED", "PARTIALLY REFUNDED"],
                "description": "billingStatus - the billing status of the order, one of: \nSUCCEEDED - the order was billed successfully (regardless of fulfilment issues). \nFAILED - payment failed when attempting to bill the customer for the order \nNOT BILLED - billing was not attempted for this order, for example if the user cancelled it before it was shipped. \nDELEGATED - billing was carried out by another agent, e.g. Shopify. Most common on the first order of a subscription.\nREFUNDED - billing was successful, but later refunded for the full amount. \nPARTIALLY REFUNDED - billing was successful, but later refunded for less than the full amount."
              }
            },
            "required": [
              "delegateId",
              "customerId",
              "productChoices",
              "boxNumber",
              "subscriptionTypeBoxNumber",
              "contractId",
              "deliveryDate",
              "price",
              "subscriptionTypeId",
              "subscriptionPhaseId",
              "state",
              "billingStatus"
            ],
            "additionalProperties": false,
            "description": "A list of historical orders for customers"
          },
          "minItems": 1
        }
      },
      "required": ["orders"],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

    Field Descriptions

    • delegateId - a unique identifier for the order, used to ensure the same order isn't accidentally re-created as a duplicate.

    • customerId - the unique identifier for the customer used in the database or customers import.

    • productChoices - the list of products delivered as part of an order, each with:

      • productId - a unique identifier for each product which must match the IDs in the provided Products import or the database.

      • quantity - records how many of each product were delivered in that order.

    • boxNumber -  The order ordinal, aka how many committed orders a customer has had so far, recording what total box number a customer is on as part of their subscription, regardless of subscription type. This should increment with refunded but not cancelled orders. A contract may not have multiple committed orders with the same box number.

    • subscriptionTypeBoxNumber - the position the user has reached in their subscription type, e.g. if using playlists.

    • contractId - the id of the subscription associated with the order. This must match a subscription provided in the Subscription Contracts data.

    • deliveryDate - the date the order was delivered on, in ISO 8601 format YYYY-MM-DD.

    • price - the price the customer paid (or was scheduled to pay until the order was cancelled) to receive the order, including any promotions.

    • state - the status of the order: committed or cancelled. An order should be be committed if it was billed/delivered successfully, even if it was later refunded. Status "cancelled" should be used for orders that were never billed or failed to bill.

    • cancellationReason - The reason for cancelling an order, if applicable (required if an order was cancelled).

    • whenCommitted - the date the order was committed (may be different from the delivery date, as this refers to the date at which an order could no longer be changed by the customer). Required if an order was committed.

    • billingStatus - the billing status of the order, one of:

      • SUCCEEDED - the order was billed successfully (regardless of fulfilment issues).

      • FAILED - payment failed when attempting to bill the customer for the order

      • NOT BILLED - billing was not attempted for this order, for example if the user cancelled it before it was shipped.

      • DELEGATED - billing was carried out by another agent, e.g. Shopify. Most common on the first order of a subscription.

      • REFUNDED - billing was successful, but later refunded for the full amount.

      • PARTIALLY REFUNDED - billing was successful, but later refunded for less than the full amount.

    • promoCode - a string field for the discount code used on an order. Optional, given not all orders will have a discount applied.

    • subscriptionTypeId - an identifier for the subscription type a given order was part of. If this does not match a subscription type provided in Subscription Types file then this value will be replaced with the matching subscription contract's subscription type id.

    • subscriptionPhaseId - an identifier for a phase within a subscription type. It is an indicator of which phase the order is generated from, and must match the ID used in the Subscription Contracts import.

    Example

    {
  "orders": [
    {
      "delegateId": "1",
      "customerId": "123456789", 
      "productChoices": [ { "productId": "1111-2222-3333", "quantity": 2 } ],
      "boxNumber": 5, 
      "subscriptionTypeBoxNumber": 5, 
      "contractId": "xxxx-yyyy-zzzz", 
      "deliveryDate": "2022-07-31", 
      "state": "committed", 
      "billingStatus": "SUCCEEDED", 
      "price": 69.99, 
      "whenCommitted": "2022-07-28", 
      "promoCode": "WELCOME-10-OFF", 
      "subscriptionTypeId": "aaaaa-bbbbbb-ccccc", 
      "subscriptionPhaseId": "xxx-yyy-zzz" 
    },
    { 
      "delegateId": "2",
      "customerId": "123456789", 
      "productChoices": [ { "productId": "3333-2222-1111", "quantity": 1 } ], 
      "boxNumber": 10, 
      "subscriptionTypeBoxNumber": 11, 
      "contractId": "llll-mmmm-nnnn", 
      "deliveryDate": "2022-06-06", 
      "state": "cancelled", 
      "billingStatus": "NOT BILLED", 
      "price": 69.99, 
      "cancellationReason": "Didn't want it anymore", 
      "promoCode": "WELCOME-10-OFF", 
      "subscriptionTypeId": "aaaaa-bbbbbb-ccccc", 
      "subscriptionPhaseId": "xxx-yyy-zzz" 
    }
  ]
}

    FAQ

    What is the difference between boxNumber and subscriptionTypeBoxNumber?

    The boxNumber refers to the total number of boxes a customer has received, whereas the subscriptionTypeBoxNumber indicates the number of boxes the customer has received with the same subscription type as this order.

    For example, a customer is on box 4 on subscription type X. They start a new subscription with subscription type Y. Their first box on the new subscription would have boxNumber 5 (total boxes received) but subscriptionTypeBoxNumber 1 (total boxes received for this subscription type).

    Do I need to import pending future orders?

    The import service currently only supports historical orders, as all future orders must be created by Bento's order generation mechanism. If you have customers with planned skip dates or edits to their usual cadence, then adjust with the adjustedDates or nextOrderOverride fields on their Subscription Contract.

    Was this article helpful?
    What's Next