Create Nibble
When needed, as determined by the Nibble Widget nibble-session-start event, call this API function from a secure
server to create a Nibble for negotiation. When successful, the full JSON response should be returned to the Nibble
Widget via your successCallback.
HTTP Request
POST https://api.nibble.website/v1/session
Headers:
X-Api-Key: XXX-XXX
X-Nibble-Api-Secret: XXXX
Content-Type: application/jsonHeader Fields
| Field | Required? | Description |
|---|---|---|
X-Api-Key | Yes | Your API Key, as provided to you by Nibble. |
X-Nibble-Api-Secret | Yes | Your API Secret, as provided to you by Nibble. |
Content-Type | Yes | Must be application/json. |
JSON Body
{
"session_token": "XXXX",
"currency_code": "GBP",
"negotiation_type": "product",
"product_id": "ABCD",
"product_name": "My Product",
"variant_id": "DEF123",
"variant_name": "Small",
"product_price": "150.00",
"threshold_price": "120.00"
"quantity": 2,
"maxQuantity": 5
}| Field | Required? | Description |
|---|---|---|
session_token | Yes | This should uniquely (or pseudo-uniquely) identify the user’s session within a reasonable period of time, and not be long lived (if a user returns days later, we expect a different Session Token to be provided). As an example, this could be a random string stored in a session cookie that expires in a few hours. |
currency_code | No | ISO 4217 alphabetic code of the currency in use for this Nibble. Optional, defaults to GBP. |
negotiation_type | No | The negotiation type which can either be set to "product" or cart for cart negotiations. Optional, defaults to "product" if not specified. |
product_id | Yes - For product negotations | A string ID uniquely identifying the product. You can specify any string as a valid ID, but all negotiations for the same product should be created with the same product_id. |
product_name | Yes - For product negotiations | The name of the product in question. This may be used by Nibble in the negotiation, or when reporting on negotiations later. |
variant_id | No - product negotiations only | A string ID uniquely identifying the variant, colourway or sub-product in question. If your product does not have such options, this field can be omitted. |
variant_name | No - product negotiations only | The name of the variant, colourway or sub-product in question. If your product does not have such options, this field can be omitted. |
original_price | Yes | For product negotiations, this should be normal retail unit price of the product. For cart negotiations, it is the total of all items in the cart, before shipping and taxes. Represented as a decimal number without currency symbol. E.g. 150.00. |
threshold_price | No | For product negotiations, this can be specified to set the minimum price that Nibble will agree to. Represented as a decimal number without currency symbol. E.g. 120.00. |
quantity | No - product negotiations only | The quantity the user has chosen to buy/negotiate for. Optional, defaults to 1 if not specified. |
max_quantity | No - product negotiations only | The maximum quantity of a product the user can negotiate on. If specified, should be set to the retailer’s current stock level for the product. Optional, defaults to 10 if not specified. |
HTTP Response
| HTTP Code | Description |
|---|---|
200 | The session was created successfully. Response body will be a JSON object that should be passed to the Nibble Widget via your successCallback. |
400 | Bad Request. One or more required fields are missing or invalid. Request body will be a JSON object including an error message to help you identify the issue: { "errorMessage": "productId must be specified" } |
401 | Unauthorized. 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." } |
About Product Prices
When creating a product negotiation, original_price is required, and should specify the list price of a single unit of the product - do not multiply price by quantity.
Normally, threshold prices are calculated as a percentage of product price, based on the rules set up in the Nibble Admin Panel. If you require finer control over threshold, you can specify a per-unit threshold price when creating a negotiation session by adding the threshold_price parameter. This parameter will override any threshold defined in rules, and sets the minimum price that Nibble will accept for this product.
Under normal circumstances, we highly recommend using your rules to set threshold prices. Specifying thresholds via the API overrides the threshold specified in your rule configuration so can cause confusion.