Skip to main content

​
Events

Currently, we support the following Events:
EntityEvents
Shoppershopper.created, shopper.updated, shopper.deleted
Client (deprecated)client.created, client.updated, client.deleted
File importfile_import.finished
Cartcart.created
Metafieldmetafield.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: 
{
  "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

FieldDescription
idBSPK’s unique identifier of the shopper
refShopper’s external reference identifier (linked by your backend or ERP system)
first_nameFirst name of the shopper
last_nameLast name of the shopper
alternate_first_nameAlternate first name of the shopper
alternate_last_nameAlternate last name of the shopper
titleTitle of the shopper
emailEmail of the shopper
mobile_phoneMobile phone of the shopper
other_phoneOther phone of the shopper
birthdayBirthday of the shopper
genderGender of the shopper (accepted values: NULL, “F” (Female), “M” (Male), “NB” (“Non-binary”))
nationalityNationality of the shopper
passport_numberPassport Number of the shopper
languageLanguage of the shopper
addressesList of shopper’s addresses
current_storeAttributes related to the shopper’s current assigned store
current_sales_associateAttributes related to the shopper’s current assigned sales associate
preferred_contact_channelThe preferred channel of the shopper
communication_preferencesWhether or not the shopper has enabled being contacted by a given channel
consentWhether or not the shopper has given consent
notify_of_new_collectionWhether or not the shopper wants to be notified of new collections
preferencesThe preferences assigned to the shopper
preferred_journeyThe Journey which the shopper is assigned to
interestsInterests of the shopper, i.e. Surf, Golfing
segmentThe Segmentation which the shopper is assigned to
referred_by_client_idUnique identifier of the client that referred this shopper
referred_atThe date when the referral was recorded in BSPK
last_contacted_atThe last date the shopper was contacted by a Sales Associate
profile_typeShopper’s profile type (enum, valid types: person or organization)
metafieldsList of metafields associated with the shopper
created_atTimestamp of when the shopper was created
updated_atTimestamp 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:

{
  "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.
FieldDescription
idBSPK’s unique identifier of the client
external_idClient’s Unique identifier (linked by your backend or ERP system)
first_nameFirst name of the client
last_nameLast name of the client
alternate_first_nameAlternate first name of the client
alternate_last_nameAlternate last name of the client
titleTitle of the client
emailEmail of the client
mobile_phoneMobile phone of the client
other_phoneOther phone of the client
birthdayBirthday of the client
genderGender of the client (accepted values: NULL, “F” (Female), “M” (Male), “NB” (“Non-binary”))
nationalityNationality of the client
passport_numberPassport Number of the client
languageLanguage of the client
addressesList of client’s addresses
current_storeAttributes related to the client’s current assigned store
current_sales_associateAttributes related to the client’s current assigned sales associate
preferred_contact_channelThe preferred channel of the client
communication_preferencesWhether or not the client has enabled being contacted by a given channel
consentWhether or not the client has given consent
notify_of_new_collectionWhether or not the client wants to be notified of new collections
preferencesThe preferences assigned to the client
preferred_journeyThe Journey which the client is assigned to
interestsInterests of that client, i.e. Surf, Golfing
segmentThe Segmentation which the client is assigned to
referred_by_client_idUnique identifier of the client that referred this client
referred_atThe date when the client referral was recorded in BSPK
last_contacted_atThe last date the client was contacted by a Sales Associate
profile_typeClient’s profile type (enum, valid types: person or organization)
metafieldsList of metafields associated with the client
created_atTimestamp of when the client was created
updated_atTimestamp of when the client was updated

​
Sample Client payload:

{
  "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

FieldDescription
idBSPK’s unique identifier of the cart
cart_typeType of the cart
shopperObject with the shopper’s details
shopper.refShopper’s external reference identifier
shopper.first_nameFirst name of the shopper
shopper.last_nameLast name of the shopper
shopper.emailEmail of the shopper
shopper.mobile_phoneMobile phone of the shopper
line_itemsArray of line items in the cart
line_items[].idBSPK’s unique identifier of the line item
line_items[].product_variant.skuSKU of the product variant
line_items[].product_variant.nameName of the product
line_items[].quantityQuantity of the line item
created_atTimestamp of when the cart was created
updated_atTimestamp of when the cart was updated

​
Sample Cart payload:

{
  "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

FieldDescription
idBSPK’s unique identifier of the metafield
namespaceNamespace of the metafield
keyKey of the metafield
valueString value of the metafield
json_valueJSON value of the metafield (when applicable)
owner_typeType of the entity that owns the metafield (e.g. Shopper)
owner_idBSPK’s unique identifier of the owner
owner_refExternal reference identifier of the owner

​
Sample Metafield payload:

{
  "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

FieldDescription
idBSPK’s unique identifier of file import
statusImport’s status: set to “error” when any errors are present or “completed” when there are no errors
started_atTimestamp of when the import started
finished_atTimestamp of when the import finished
file_nameName of imported file
s3_bucket_nameName of S3 bucket where imported file was dropped
processed_rows_countNumber of successfully processed rows
error_rows_countNumber of rows that failed to process successfully
errorsAn array of errors where each error is defined by its line number in import file and the error message
warningsAn array of warnings where each warning is defined by its line number in import file and the warning message

​
Sample File import payload:

{
  "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": []
  }
}