> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bspk.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Events and Payloads
## Events
Currently, we support the following Events:
| Entity | Events |
| :-------------------- | :------------------------------------------------------------ |
| Shopper | `shopper.created`, `shopper.updated`, `shopper.deleted` |
| Client *(deprecated)* | `client.created`, `client.updated`, `client.deleted` |
| File import | `file_import.finished` |
| Cart | `cart.created` |
| Metafield | `metafield.created`, `metafield.updated`, `metafield.deleted` |
The `client.*` events are deprecated and will be removed in a future version. Use the equivalent `shopper.*` events instead.
## Payloads
Every event payload has a base structure as follows:
```json theme={null}
{
"event_name": "name_of.event",
"object": {
"field1": "object specific field",
"field2": "object specific field"
}
}
```
**event\_name**: Name of the event that triggered the webhook event.
**object**: Object filled with data specific to each entity.
### Shopper payload
| Field | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------- |
| id | BSPK's unique identifier of the shopper |
| ref | Shopper's external reference identifier (linked by your backend or ERP system) |
| first\_name | First name of the shopper |
| last\_name | Last name of the shopper |
| alternate\_first\_name | Alternate first name of the shopper |
| alternate\_last\_name | Alternate last name of the shopper |
| title | Title of the shopper |
| email | Email of the shopper |
| mobile\_phone | Mobile phone of the shopper |
| other\_phone | Other phone of the shopper |
| birthday | Birthday of the shopper |
| gender | Gender of the shopper (accepted values: NULL, "F" (Female), "M" (Male), "NB" ("Non-binary")) |
| nationality | Nationality of the shopper |
| passport\_number | Passport Number of the shopper |
| language | Language of the shopper |
| addresses | List of shopper's addresses |
| current\_store | Attributes related to the shopper's current assigned store |
| current\_sales\_associate | Attributes related to the shopper's current assigned sales associate |
| preferred\_contact\_channel | The preferred channel of the shopper |
| communication\_preferences | Whether or not the shopper has enabled being contacted by a given channel |
| consent | Whether or not the shopper has given consent |
| notify\_of\_new\_collection | Whether or not the shopper wants to be notified of new collections |
| preferences | The preferences assigned to the shopper |
| preferred\_journey | The Journey which the shopper is assigned to |
| interests | Interests of the shopper, i.e. Surf, Golfing |
| segment | The Segmentation which the shopper is assigned to |
| referred\_by\_client\_id | Unique identifier of the client that referred this shopper |
| referred\_at | The date when the referral was recorded in BSPK |
| last\_contacted\_at | The last date the shopper was contacted by a Sales Associate |
| profile\_type | Shopper's profile type (enum, valid types: person or organization) |
| metafields | List of metafields associated with the shopper |
| created\_at | Timestamp of when the shopper was created |
| updated\_at | Timestamp of when the shopper was updated |
The Shopper payload uses `ref` as the external identifier field, while the deprecated Client payload uses `external_id`.
#### Sample Shopper payload:
```json theme={null}
{
"event_name": "shopper.updated",
"object": {
"id": 123,
"ref": "C-720",
"first_name": "Mark",
"last_name": "Desmond",
"alternate_first_name": "标记",
"alternate_last_name": "德斯蒙德",
"title": "Mr.",
"current_store": {
"external_id": "STR-001",
"name": "LA Store",
"external_id_2": "ANOTHER-ID-876",
"country_code": "US"
},
"current_sales_associate": {
"full_name": "John Doe",
"external_id": "SA-123",
"external_id_2": "ANOTHER-ID-456",
"email": "john.doe@example.com"
},
"email": "mark.d@email.com",
"mobile_phone": "+1 555 98765998",
"other_phone": "+1 555 4431009",
"birthday": "1980-01-23",
"gender": "M",
"nationality": "French",
"passport_number": "WT0010002098",
"language": "FR",
"addresses": [
{
"address": "661 N Park Ave",
"address_2": "Apartment #106",
"address_3": "",
"address_4": "",
"city": "Shawnee",
"state": "Oklahoma(OK)",
"zip": "74801",
"country_code": "USA"
}
],
"preferred_contact_channel": "email",
"communication_preferences": {
"chat_opt_in": true,
"email_opt_in": true,
"phone_opt_in": true,
"whatsapp_opt_in": false,
"wechat_opt_in": false,
"line_opt_in": false,
"opt_out": false
},
"consent": true,
"notify_of_new_collection": true,
"preferences": [
{ "name": "styles", "value": ["Business (Mon-Fri)"] },
{ "name": "profession", "value": ["Real Estate"] }
],
"interests": [ "Surf", "Golfing" ],
"preferred_journey": "special_order",
"segment": "VIP",
"referred_by_client_id": "CL-123",
"referred_at": "2021-07-20T09:00:00Z",
"last_contacted_at": "2021-07-23T09:00:00Z",
"profile_type": "person",
"metafields": [
{ "namespace": "loyalty", "key": "tier", "value": "gold", "json_value": null }
],
"created_at": "2021-01-10T15:00:00Z",
"updated_at": "2021-07-23T09:00:00Z"
}
}
```
### Client payload *(deprecated)*
The `client.*` events are deprecated. Use the `shopper.*` events instead. The key difference is that the Client payload uses `external_id` while the Shopper payload uses `ref`.
| Field | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------ |
| id | BSPK's unique identifier of the client |
| external\_id | Client's Unique identifier (linked by your backend or ERP system) |
| first\_name | First name of the client |
| last\_name | Last name of the client |
| alternate\_first\_name | Alternate first name of the client |
| alternate\_last\_name | Alternate last name of the client |
| title | Title of the client |
| email | Email of the client |
| mobile\_phone | Mobile phone of the client |
| other\_phone | Other phone of the client |
| birthday | Birthday of the client |
| gender | Gender of the client (accepted values: NULL, "F" (Female), "M" (Male), "NB" ("Non-binary")) |
| nationality | Nationality of the client |
| passport\_number | Passport Number of the client |
| language | Language of the client |
| addresses | List of client's addresses |
| current\_store | Attributes related to the client's current assigned store |
| current\_sales\_associate | Attributes related to the client's current assigned sales associate |
| preferred\_contact\_channel | The preferred channel of the client |
| communication\_preferences | Whether or not the client has enabled being contacted by a given channel |
| consent | Whether or not the client has given consent |
| notify\_of\_new\_collection | Whether or not the client wants to be notified of new collections |
| preferences | The preferences assigned to the client |
| preferred\_journey | The Journey which the client is assigned to |
| interests | Interests of that client, i.e. Surf, Golfing |
| segment | The Segmentation which the client is assigned to |
| referred\_by\_client\_id | Unique identifier of the client that referred this client |
| referred\_at | The date when the client referral was recorded in BSPK |
| last\_contacted\_at | The last date the client was contacted by a Sales Associate |
| profile\_type | Client's profile type (enum, valid types: person or organization) |
| metafields | List of metafields associated with the client |
| created\_at | Timestamp of when the client was created |
| updated\_at | Timestamp of when the client was updated |
#### Sample Client payload:
```json theme={null}
{
"event_name": "client.updated",
"object": {
"id": 123,
"external_id": "C-720",
"first_name": "Mark",
"last_name": "Desmond",
"alternate_first_name": "标记",
"alternate_last_name": "德斯蒙德",
"title": "Mr.",
"current_store": {
"external_id": "STR-001",
"name": "LA Store",
"external_id_2": "ANOTHER-ID-876",
"country_code": "US"
},
"current_sales_associate": {
"full_name": "John Doe",
"external_id": "SA-123",
"external_id_2": "ANOTHER-ID-456",
"email": "john.doe@example.com"
},
"email": "mark.d@email.com",
"mobile_phone": "+1 555 98765998",
"other_phone": "+1 555 4431009",
"birthday": "1980-01-23",
"gender": "M",
"nationality": "French",
"passport_number": "WT0010002098",
"language": "FR",
"addresses": [
{
"address": "661 N Park Ave",
"address_2": "Apartment #106",
"address_3": "",
"address_4": "",
"city": "Shawnee",
"state": "Oklahoma(OK)",
"zip": "74801",
"country_code": "USA"
}
],
"preferred_contact_channel": "email",
"communication_preferences": {
"chat_opt_in": true,
"email_opt_in": true,
"phone_opt_in": true,
"whatsapp_opt_in": false,
"wechat_opt_in": false,
"line_opt_in": false,
"opt_out": false
},
"consent": true,
"notify_of_new_collection": true,
"preferences": [
{ "name": "styles", "value": ["Business (Mon-Fri)"] },
{ "name": "profession", "value": ["Real Estate"] }
],
"interests": [ "Surf", "Golfing" ],
"preferred_journey": "special_order",
"segment": "VIP",
"referred_by_client_id": "CL-123",
"referred_at": "2021-07-20T09:00:00Z",
"last_contacted_at": "2021-07-23T09:00:00Z",
"profile_type": "person",
"metafields": [
{ "namespace": "loyalty", "key": "tier", "value": "gold", "json_value": null }
],
"created_at": "2021-01-10T15:00:00Z",
"updated_at": "2021-07-23T09:00:00Z"
}
}
```
### Cart payload
| Field | Description |
| :----------------------------------- | :---------------------------------------- |
| id | BSPK's unique identifier of the cart |
| cart\_type | Type of the cart |
| shopper | Object with the shopper's details |
| shopper.ref | Shopper's external reference identifier |
| shopper.first\_name | First name of the shopper |
| shopper.last\_name | Last name of the shopper |
| shopper.email | Email of the shopper |
| shopper.mobile\_phone | Mobile phone of the shopper |
| line\_items | Array of line items in the cart |
| line\_items\[].id | BSPK's unique identifier of the line item |
| line\_items\[].product\_variant.sku | SKU of the product variant |
| line\_items\[].product\_variant.name | Name of the product |
| line\_items\[].quantity | Quantity of the line item |
| created\_at | Timestamp of when the cart was created |
| updated\_at | Timestamp of when the cart was updated |
#### Sample Cart payload:
```json theme={null}
{
"event_name": "cart.created",
"object": {
"id": 456,
"cart_type": "wishlist",
"shopper": {
"ref": "C-720",
"first_name": "Mark",
"last_name": "Desmond",
"email": "mark.d@email.com",
"mobile_phone": "+1 555 98765998"
},
"line_items": [
{
"id": 1,
"product_variant": {
"sku": "SKU-001",
"name": "Leather Bag"
},
"quantity": 1
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
```
### Metafield payload
| Field | Description |
| :---------- | :---------------------------------------------------------- |
| id | BSPK's unique identifier of the metafield |
| namespace | Namespace of the metafield |
| key | Key of the metafield |
| value | String value of the metafield |
| json\_value | JSON value of the metafield (when applicable) |
| owner\_type | Type of the entity that owns the metafield (e.g. `Shopper`) |
| owner\_id | BSPK's unique identifier of the owner |
| owner\_ref | External reference identifier of the owner |
#### Sample Metafield payload:
```json theme={null}
{
"event_name": "metafield.created",
"object": {
"id": 789,
"namespace": "loyalty",
"key": "tier",
"value": "gold",
"json_value": null,
"owner_type": "Shopper",
"owner_id": 123,
"owner_ref": "C-720"
}
}
```
### File import payload
| Field | Description |
| :--------------------- | :----------------------------------------------------------------------------------------------------------- |
| id | BSPK's unique identifier of file import |
| status | Import's status: set to "error" when any errors are present or "completed" when there are no errors |
| started\_at | Timestamp of when the import started |
| finished\_at | Timestamp of when the import finished |
| file\_name | Name of imported file |
| s3\_bucket\_name | Name of S3 bucket where imported file was dropped |
| processed\_rows\_count | Number of successfully processed rows |
| error\_rows\_count | Number of rows that failed to process successfully |
| errors | An array of errors where each error is defined by its line number in import file and the error message |
| warnings | An array of warnings where each warning is defined by its line number in import file and the warning message |
#### Sample File import payload:
```json theme={null}
{
"event_name": "file_import.finished",
"object": {
"id": 123,
"status": "error",
"started_at": "2022-03-02T13:55:29.000Z",
"finished_at": "2022-03-07T15:12:30.390Z",
"file_name": "PRODUCT_V2-20220101.csv",
"s3_bucket_name": "bspk-company-integration-prod",
"processed_rows_count": 200,
"error_rows_count": 2,
"errors": [
{
"line": 5,
"err_msg": ["Store not found for store_id: S_5"]
},
{
"line": 8,
"err_msg": ["Product Variant not found for product_ref: ID_1 and sku: SKU_4"]
}
],
"warnings": []
}
}
```