Skip to main content
Metronome supports switching between any combination of Stripe, NetSuite, and marketplace providers (AWS, Azure, GCP) on a contract. A contract stores a billing provider configuration schedule — an ordered list of segments each with an effective_at timestamp aligned to a billing period boundary. The active configuration for a given invoice is the segment with the latest effective_at date before the service period end date or issued~at date if there is no service period end date.

​
Supported transitions

From → ToCurrent periodNext period
Stripe → Stripe✅✅
Stripe → NetSuite✅✅
NetSuite → Stripe✅✅
Stripe → Marketplace (AWS / Azure / GCP)❌✅
Marketplace → Stripe❌✅
Marketplace → Marketplace❌✅
NetSuite → Marketplace❌✅
Marketplace → NetSuite❌✅

​
Schedule a change

Use the add_billing_provider_configuration_update field on POST v2/contracts/edit. The effective_at controls when the new configuration takes effect: START_OF_CURRENT_PERIOD or START_OF_NEXT_PERIOD. Example: Correct a Stripe misconfiguration, effective immediately Switch from one Stripe configuration to another at the start of the current period. The current draft invoice will be routed to the new configuration. If an invoice was already finalized and sent to Stripe during this period, the new configuration will not apply to it — all invoices are guaranteed to be sent exactly once. 
curl https://api.metronome.com/v2/contracts/edit \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "contract_id": "6058587f-763c-400f-a822-3edb3eb2b86b",
    "add_billing_provider_configuration_update": {
      "billing_provider_configuration": {
        "billing_provider_configuration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      },
      "schedule": {
        "effective_at": "START_OF_CURRENT_PERIOD"
      }
    }
  }'
Example: Transition from Stripe to AWS Marketplace, effective next period All invoices from the current billing period are routed based on the existing Stripe configuration. The marketplace configuration takes effect at the start of the next period. 
curl https://api.metronome.com/v2/contracts/edit \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "contract_id": "6058587f-763c-400f-a822-3edb3eb2b86b",
    "add_billing_provider_configuration_update": {
      "billing_provider_configuration": {
        "billing_provider_configuration_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      },
      "schedule": {
        "effective_at": "START_OF_NEXT_PERIOD"
    }
  }'

​
View the billing provider configuration schedule

Fetch a contract using POST v2/contracts/get to view the full schedule. The customer_billing_provider_configuration field returns the currently-active configuration unchanged. The billing_provider_configuration_schedule field returns an ordered list of all past, current, and future segments. 
{
  "data": {
    "id": "6058587f-763c-400f-a822-3edb3eb2b86b",
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "customer_billing_provider_configuration": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "billing_provider": "stripe",
      "delivery_method": "direct_to_billing_provider"
    },
    "billing_provider_configuration_schedule": [
      {
        "billing_provider_configuration": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "billing_provider": "stripe",
          "delivery_method": "direct_to_billing_provider"
        },
        "effective_at": "2025-01-01T00:00:00.000Z",
        "effective_until": "2025-06-01T00:00:00.000Z"
      },
      {
        "billing_provider_configuration": {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "billing_provider": "aws_marketplace",
          "delivery_method": "direct_to_billing_provider"
        },
        "effective_at": "2025-06-01T00:00:00.000Z",
        "effective_until": null
      }
    ]
  }
}

​
Constraints and considerations

Changes align to billing period boundaries. START_OF_CURRENT_PERIOD resolves to the start of the current usage invoice service period. START_OF_NEXT_PERIOD resolves to the start of the following service period. Each invoice maps to exactly one billing provider configuration based on its service period start date.
Marketplace transitions require START_OF_NEXT_PERIOD. Marketplace billing is metered from the start of a period, so mid-period transitions are not supported. When transitioning to a marketplace, the current period completes fully on the existing configuration. When transitioning away, the marketplace continues to bill through the end of the current period.
Threshold billing must be disabled before switching to a marketplace provider. If a contract has an active threshold billing configuration, it must be removed before scheduling a transition to any marketplace provider.
customer_billing_provider_configuration is unchanged and backward compatible. The existing field on contracts/get and contracts/list responses continues to return the currently-active configuration. No changes are required to existing integrations that read this field.
A maximum of 10 schedule segments per contract. If you need additional capacity on a specific contract, contact your account team.
To cancel a scheduled future change, schedule a new segment covering the same period. The latest segment takes precedence.