Integration API

Create an audience. The audience can be created directly from scratch or can come from third party platforms.

Note: Audiences can also be created from scratch via the Campaign Manager. See the docs.

To create an audience from an existing audience from a technology partner:

1. Set the integration property to mparticle, segment etc., depending on a third-party platform.
2. Set integrationId to the ID of this audience in a third-party platform.

To create an audience from an existing audience in another platform:

1. Do not use the integration property.
2. Set integrationId to the ID of this audience in the 3rd-party platform.

To create an audience from scratch:

1. Only set the name property.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.

Delete an audience created by a third-party integration.

Warning: This endpoint also removes any associations recorded between a customer profile and this audience.

Note: Audiences can also be deleted via the Campaign Manager. See the docs.

Update the name of the given audience created by a third-party integration. Sending a request to this endpoint does not trigger the Rule Engine.

To update the audience's members, use the Update customer profile endpoint.

Remove all members from this audience.

Add customer profiles to or remove them from an audience.

The endpoint supports 1000 audience actions (add or remove) per request.

Note: You can also do this using the Update audience effect.

Update the specified profile attributes to the provided values for all customers in the specified audience.

Perform the following actions for a given cart item catalog:

• Add an item to the catalog.
• Add multiple items to the catalog.
• Update the attributes of an item in the catalog.
• Update the attributes of multiple items in the catalog.
• Remove an item from the catalog.
• Remove multiple items from the catalog.

You can either add, update, or delete up to 1000 cart items in a single request. Each item synced to a catalog must have a unique SKU.

Important: You can perform only one type of action in a single sync request. Syncing items with duplicate SKU values in a single request returns an error message with a 400 status code.

For more information, read managing cart item catalogs.

Filtering cart items

Use cart item attributes to filter items and select the ones you want to edit or delete when editing or deleting more than one item at a time.

The filters array contains an object with the following properties:

• attr: A cart item attribute connected to the catalog. It is applied to all items in the catalog.

• op: The filtering operator indicating the relationship between the value of each cart item in the catalog and the value of the value property for the attribute selected in attr.

  The value of op can be one of the following:

  • EQ: Equal to value
  • LT: Less than value
  • LE: Less than or equal to value
  • GT: Greater than value
  • GE: Greater than or equal to value
  • IN: One of the comma-separated values that value is set to.

  Note: GE, LE, GT, LT are for numeric values only.

• value: The value of the attribute selected in attr.

Payload examples

Synchronization actions are sent as PUT requests. See the structure for each action:

{
  "actions": [
    {
      "payload": {
        "attributes": {
          "color": "Navy blue",
          "type": "shoes"
        },
        "replaceIfExists": true,
        "sku": "SKU1241028",
        "price": 100,
        "product": {
          "name": "sneakers"
        }
      },
      "type": "ADD"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "attributes": {
          "color": "Navy blue",
          "type": "shoes"
        },
        "replaceIfExists": true,
        "sku": "SKU1241027",
        "price": 100,
        "product": {
          "name": "sneakers"
        }
      },
      "type": "ADD"
    },
    {
      "payload": {
        "attributes": {
          "color": "Navy blue",
          "type": "shoes"
        },
        "replaceIfExists": true,
        "sku": "SKU1241028",
        "price": 100,
        "product": {
          "name": "sneakers"
        }
      },
      "type": "ADD"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "attributes": {
          "age": 11,
          "origin": "germany"
        },
        "createIfNotExists": false,
        "sku": "SKU1241028",
        "product": {
          "name": "sneakers"
        }
      },
      "type": "PATCH"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "attributes": {
          "color": "red"
        },
        "filters": [
          {
            "attr": "color",
            "op": "EQ",
            "value": "blue"
          }
        ]
      },
      "type": "PATCH_MANY"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "sku": "SKU1241028"
      },
      "type": "REMOVE"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "filters": [
          {
            "attr": "color",
            "op": "EQ",
            "value": "blue"
          }
        ]
      },
      "type": "REMOVE_MANY"
    }
  ]
}

{
  "actions": [
    {
      "payload": {
        "filters": [
          {
            "attr": "size",
            "op": "GT",
            "value": "45"
          }
        ]
      },
      "type": "REMOVE_MANY"
    }
  ]
}

Create a coupon reservation for the specified customer profiles on the specified coupon. You can also create a reservation via the Campaign Manager using the Create coupon code reservation effect.

Note:

• If the Reservation mandatory option was selected when creating the specified coupon, the endpoint creates a hard reservation, meaning only users who have this coupon code reserved can redeem it. Otherwise, the endpoint creates a soft reservation, meaning the coupon is associated with the specified customer profiles (they show up when using the List customer data endpoint), but any user can redeem it. This can be useful, for example, to display a coupon wallet for customers when they visit your store.

• If the Coupon visibility option was selected when creating the specified coupon, the coupon code is implicitly soft-reserved for all customers, and the code will be returned for all customer profiles in the List customer data endpoint.

• This endpoint overrides the coupon reservation limit set when the coupon is created. To ensure that coupons cannot be reserved after the reservation limit is reached, use the Create coupon code reservation effect in the Rule Builder and the Update customer session endpoint.

To delete a reservation, use the Delete reservation endpoint.

Remove all the coupon reservations from the provided customer profile integration IDs and the provided coupon code.

Return all customers that have this coupon marked as reserved. This includes hard and soft reservations.

Update or create a Customer Profile. This endpoint triggers the Rule Builder.

You can use this endpoint to:

• Set attributes on the given customer profile. Ensure you create the attributes in the Campaign Manager, first.
• Modify the audience the customer profile is a member of.

Update (or create) up to 1000 customer profiles in 1 request.

The integrationId must be any identifier that remains stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

A customer profile can be linked to one or more sessions.

Note: This endpoint does not trigger the Rule Engine. To trigger the Rule Engine for customer profile updates, use the Update customer profile endpoint.

Delete all attributes on the customer profile and on entities that reference this customer profile.

Important:

• Customer data is deleted from all Applications in the environment that the API key belongs to. For example, if you use this endpoint with an API key that belongs to a sandbox Application, customer data will be deleted from all sandbox Applications. This is because customer data is shared between Applications from the same environment.
• To preserve performance, we recommend avoiding deleting customer data during peak-traffic hours.

Return the customer inventory regarding entities referencing this customer profile's integrationId.

Typical entities returned are: customer profile information, referral codes, loyalty points, loyalty cards and reserved coupons. Reserved coupons also include redeemed coupons.