Skip to main content

Best practices

Practices that keep an integration reliable and its errors easy to find.

Validate before sending​

Don't rely on the API to validate your input. Before sending, check that:

  • Required fields (for example name, custom_id, segment) are present and not empty.
  • Records you refer to (contacts, products) exist, or are created first.
  • Monetary values are positive numbers with the right currency code.

Call the API in the right order​

A record must exist before another record can refer to it:

  1. Products: sync the product catalog first.
  2. Contacts: create or update contacts before adding events or deals to them.
  3. Deals: create orders after their contacts and products exist.
  4. Events: send them after their contact exists.

Use update_or_create for safe retries​

The update_or_create endpoints for contacts and deals are idempotent: sending the same request twice has the same result as sending it once, so they are safe to retry after a network failure. Use them instead of a plain POST when you can.

Handle errors by status code​

See HTTP response codes for what to do with each status code, and Rate limits for retrying after 429.

Log requests and responses​

Log each request with its response, so you can debug problems later. Include:

  • The endpoint URL and method.
  • The request body, with sensitive data removed.
  • The response status code and body.
  • A timestamp and an ID that links the request to your own data (for example your order ID).