Use the Report Sale API endpoint to notify Nibble of a sale completed in your systems.

For all sales resulting from a Nibble negotiation, you must notify Nibble of the sale.

If you wish to take advantage of Nibble’s A/B testing process, you must notify Nibble of all sales, even ones that did not involve Nibble negotiation.

HTTP Request

You can send your notification immediately after a sale, or group requests in batches of up to 50 sales at a time.

The request is an HTTPs POST request, with JSON content and the usual Nibble authentication headers. Both X-Api-Key and X-Nibble-Api-Secret are required.

POST https://api.nibble.website/v1/sales
Headers:
    X-Api-Key: YOUR_API_KEY_HERE
    X-Nibble-Api-Secret: YOUR_API_SECRET_HERE
    Content-Type: application/json

Header Fields

FieldRequired?Description
X-Api-KeyYesYour API Key, as provided to you by Nibble.
X-Nibble-Api-SecretYesYour API Secret, as provided to you by Nibble.
Content-TypeYesMust be application/json.

JSON Body

The request body must be a JSON object, with a root key sales, keying a list of sales objects.

{
    "sales": [
        {
            "purchase_date_time": "2023-04-21T14:30Z",
            "session_token": "XXXX-XXX-XXX",
            "order_number": "ZY2314",
            "currency_code": "USD",
            "total_item_price": "10.50",
            "nibble_id": "AB4534",
            "items": [
                {
                    "product_id": "ABCD",
                    "variant_id": "EFGH",
                    "quantity": 2
                },
                {...}
            ]
        },
        {
            "purchase_date_time": "2023-04-21T14:30Z",
            "session_token": "XXXX-XXX-XXX",
            "order_number": "ZY2314",
            "currency_code": "GBP",
            "total_item_price": "5.00",
            "items": [
                {
                    "product_id": "ABCD",
                    "variant_id": "EFGH",
                    "quantity": 1,
                    "nibble_id": "AB4535"
                },
                {...}
            ]
        },
        {...}
    ]
}

Sale Objects

Each sale object consists of:

FieldRequired?Description
purchase_date_timeYesThe date and time of the purchase, formatted as an ISO 8601 string. The time zone must be UTC or the string must contain ISO 8601 time zone information.
session_tokenYesThe unique identifier for the user’s browsing session. Must match the one used when the Nibble button was shown to the user, and used when starting a negotiation.
order_numberYesA string identifying the sales record in your system. Used for reconciliation, to match Nibble’s records with yours.
currency_codeYesThe ISO 4217 three-letter currency code specifying the currency of this sale.
total_item_priceYesA string representing the decimal value of the total price of all items in the sale, after all discounts are applied.
nibble_idNoIf the sale involved a Nibble negotiation on the cart, the nibble_id for that negotiation must be present in the sale object. If not, nibble_id can be left out of the object or left null.
itemsYesA list of all items purchased in this sale transaction, including items that did not involve a Nibble negotiation.

Item Objects

Each item object consists of:

FieldRequired?Description
product_idYesA string uniquely identifying the product. This should match the value used when creating Nibble product negotatiations.
product_idNoA string uniquely identifying the product variant, colour-way or sub-product. If your product does not have such options, this field can be omitted. This should match the value used when creating Nibble product negotiations.
quantityNoAn integer representing how many of this item were purchased. Assumed to be 1 if not specified.
nibble_idNoIf the item was added to cart as the result of a Nibble product negotiation, this field must be present and contain the nibbleId for that negotiation. Note: for product negotiations with addons, the nibbleId should be present on both the original item and the addon item.
isNibbleAddonItemYesA boolean indicating whether this item was added to the cart as an ‘addon’ item from a Nibble negotiation. Should be false for most items, but true if the item is an addon (e.g. a Gift With Purchase).

HTTP Response

The sales reporting endpoint indicates success using the HTTP status code. In the case of errors, the response body will be a JSON object containing error information.

HTTP CodeDescription
200The sales have been successfully recorded.
400Bad Request. The request is not of the expected format, or it does not contain the required data. The response body will include an error message to help you identify the issue: { "errorMessage": "order_number must be specified" }
401Unauthorized. The API Key and/or Secret are missing, invalid or expired. Request body will be a JSON object including an error message to help you identify the issue: { "errorMessage": "API Secret is not valid." }