List contracts associated with a package

For a given package, returns all contract IDs and customer IDs associated with the package over a specific time period.

Use this endpoint to:

• Understand which customers are provisioned on a package at any given time for internal cohort management
• Manage customer migrations to a new package. For example, to migrate all active customers to a new package, call this endpoint, end contracts, and provision customers on a new package.

Usage guidelines:

Use the starting_at, covering_date, and include_archived parameters to filter the list of returned contracts. For example, to list only currently active contracts, pass covering_date equal to the current time.

POST /v1/packages/listContractsOnPackage

List contracts associated with a package

cURL

curl --request POST \
  --url https://api.metronome.com/v1/packages/listContractsOnPackage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "package_id": "13117714-3f05-48e5-a6e9-a66093f13b4d"
}
'

200

{
  "contracts": [
    {
      "contract_id": "63798fdb-6883-4e53-8365-74d42a3e1f09",
      "customer_id": "f0b78a5e-01d1-4ed1-96da-05bc225963ec",
      "starting_at": "2024-01-01T00:00:00Z"
    }
  ],
  "next_page": "eyJvZmZzZXQiOjF9"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limit · integer

Max number of results that should be returned

Required range: 1 <= x <= 100

next_page · string

Cursor that indicates where the next page of results should start.

Body

application/json

Package ID and optional filters

package_id · string<uuid> · required

starting_at · string<date-time>

Optional RFC 3339 timestamp. Only include contracts that started on or after this date. This cannot be provided if covering_date filter is provided.

covering_date · string<date-time>

Optional RFC 3339 timestamp. Only include contracts active on the provided date. This cannot be provided if starting_at filter is provided.

include_archived · boolean

Default false. Determines whether to include archived contracts in the results

Response

200

application/json

Success

contracts · object[] · required

Show child attributes

next_page · string | null