Customer.io
v1.0.0
OpenAPI 3.1.0

Write to a collection

US region

Client Libraries
Shell Curl

Write to a collection

​

Queue a change to a collection's rows and get a write id back right away, so large writes don't time out. Customer.io applies writes to a collection one at a time, in the order it receives them. Use look up a collection write to check the result.

Use mode to choose how to change the collection:

  • replace removes every row in the collection and adds the rows you send in data or at a url. You can set the collection's key_field in the same request.
  • add, upsert, update, and delete change only the rows whose keys you send, so the collection needs a key field. Customer.io applies a keyed write all or nothing: if any row in the request is invalid, Customer.io doesn't change any rows.
Path Parameters
  • collection_id
    Type: integer
    required

    The identifier for a collection.

Body
application/json
    • data
      Type: array object[]
      required

      Every row of the collection. This replaces the collection's current rows.

    • mode
      enum
      const:  
      replace
      required
      values
      • replace
    • key_field
      Type: string

      The attribute that holds each row's unique key, like sku, similar to a primary key in a database table. Set a key field to add, change, delete, or read individual rows without replacing the whole collection. Each row needs a unique, non-empty string or number in this attribute, up to 1,024 bytes.

Responses
  • application/json
  • 404

    The collection id does not exist.

  • 422

    Customer.io couldn't accept the write. The response explains what to fix. For a keyed write, each error's source.pointer names the failed row, like /data/attributes/data/1.

  • application/json
Request Example for post/v1/collections/{collection_id}/writes
{
  "data": [
    {
      "sku": "A-100",
      "price": 19
    },
    {
      "sku": "A-101",
      "price": 24
    }
  ],
  "mode": "upsert"
}

{
  "write": {
    "id": "01JD8X4Q6R2W7N3K5M9P1T0VZC",
    "state": "queued"
  }
}

Customer.io queued the write.