price-changes

Stable. Describes behaviour that is built and covered by tests in this repository.

GET `/v1/price-changes` #

The price changes made, newest first

Each with the number of subscriptions that are waiting for their renewal (scheduled), were moved (applied), were withdrawn or were skipped. The latest 100.

Parameters

Name	In	Type	Description
`plan_code`	query	string	Only the price changes of this plan

Responses

Status	Meaning	Body
`200`	OK	ListPriceChangesResponse

Example response

{
  "price_changes": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "plan_code": "string",
      "from_version": 1,
      "to_version": 1,
      "notice_days": 1,
      "effective_time": "2026-11-03T10:15:00Z",
      "effective_from": "2026-11-03T10:15:00Z",
      "notice_send_days_before": 1,
      "state": "open",
      "created_by": "string",
      "create_time": "2026-11-03T10:15:00Z",
      "withdraw_time": "2026-11-03T10:15:00Z",
      "withdrawn_by": "string",
      "scheduled": 1,
      "applied": 1,
      "withdrawn": 1,
      "skipped": 1
    }
  ]
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/price-changes \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

GET `/v1/price-changes/{id}` #

One price change with its subscriptions and what became of each

The subscriptions by customer, a page at a time (page_size 1 to 500, default 500; next_page_token is empty on the last page), optionally only those in one state. The state of a scheduled one follows its change - waiting (scheduled), applied at the renewal, or withdrawn.

Parameters

Name	In	Type
`id` required	path	string · uuid
`state`	query	`scheduled` \| `applied` \| `withdrawn` \| `skipped`
`page_size`	query	integer
`page_token`	query	string

Responses

Status	Meaning	Body
`200`	OK	GetPriceChangeResponse
`400`	Error envelope	Error
`404`	Error envelope	Error

Example response

{
  "price_change": {
    "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "plan_code": "string",
    "from_version": 1,
    "to_version": 1,
    "notice_days": 1,
    "effective_time": "2026-11-03T10:15:00Z",
    "effective_from": "2026-11-03T10:15:00Z",
    "notice_send_days_before": 1,
    "state": "open",
    "created_by": "string",
    "create_time": "2026-11-03T10:15:00Z",
    "withdraw_time": "2026-11-03T10:15:00Z",
    "withdrawn_by": "string",
    "scheduled": 1,
    "applied": 1,
    "withdrawn": 1,
    "skipped": 1
  },
  "items": [
    {
      "subscription_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "customer_external_id": "string",
      "state": "scheduled",
      "reason": "string",
      "effective_time": "2026-11-03T10:15:00Z",
      "notify_time": "2026-11-03T10:15:00Z"
    }
  ],
  "next_page_token": "string"
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/price-changes/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/price-changes/{id}/retry` #

Try the skipped subscriptions of a price change again

Runs the price change again with the notice it was made with, for the subscriptions that were skipped (a renewal that was too close may be far enough now) and any that joined the version since. What is scheduled already is left alone. Refused with 409 plans.price_change.withdrawn once it was withdrawn.

Parameters

Name	In	Type	Description
`id` required	path	string · uuid

Responses

Status	Meaning	Body
`200`	OK	SchedulePriceChangeResponse
`404`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "scheduled": 1,
  "scheduled_subscription_ids": [
    "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e"
  ],
  "skipped": [
    {
      "subscription_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "customer_external_id": "string",
      "reason": "renews_soon"
    }
  ],
  "to_version": 1,
  "notice_days": 1
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/price-changes/<id>/retry \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/price-changes/{id}/withdraw` #

Cancel every change of a price change that is still waiting

Closes the price change and cancels the scheduled changes that have not taken effect, so those customers stay on the old price. A change that was applied stays, and the mail that was sent is not taken back (tell those customers yourself). Calling it again finishes what an interrupted call left; a new run makes a new price change.

Parameters

Name	In	Type	Description
`id` required	path	string · uuid

Responses

Status	Meaning	Body
`200`	OK	WithdrawPriceChangeResponse
`404`	Error envelope	Error

Example response

{
  "price_change": {
    "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "plan_code": "string",
    "from_version": 1,
    "to_version": 1,
    "notice_days": 1,
    "effective_time": "2026-11-03T10:15:00Z",
    "effective_from": "2026-11-03T10:15:00Z",
    "notice_send_days_before": 1,
    "state": "open",
    "created_by": "string",
    "create_time": "2026-11-03T10:15:00Z",
    "withdraw_time": "2026-11-03T10:15:00Z",
    "withdrawn_by": "string",
    "scheduled": 1,
    "applied": 1,
    "withdrawn": 1,
    "skipped": 1
  },
  "withdrawn": 1
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/price-changes/<id>/withdraw \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Models

Error

Field	Type	Description
`error` required	object

GetPriceChangeResponse

Field	Type	Description
`price_change` required	PriceChange
`items` required	array of PriceChangeItem
`next_page_token` required	string

ListPriceChangesResponse

Field	Type	Description
`price_changes` required	array of PriceChange

PriceChange

Field	Type	Description
`id` required	string · uuid
`plan_code` required	string
`from_version` required	integer
`to_version` required	integer
`notice_days` required	integer	The notice of the latest run
`effective_time` required	string · date-time	The earliest date a customer's price changes: the first scheduled renewal (until one is scheduled, the end of the notice)
`effective_from` required	string · date-time	The date the seller chose the new price to start from; null when each subscription moves on its next renewal
`notice_send_days_before` required	integer	Days before the new price that the notice mails go out; 0 when they go out as the run schedules the change
`state` required	`open` \| `withdrawn`
`created_by` required	string	The signed-in person's address, key:<id> for an API key, or the operator
`create_time` required	string · date-time
`withdraw_time` required	string · date-time
`withdrawn_by` required	string
`scheduled` required	integer	Subscriptions waiting for their renewal
`applied` required	integer	Subscriptions moved to the new price
`withdrawn` required	integer	Subscriptions whose change was cancelled (by a withdrawal, or because the seller or the customer changed the subscription)
`skipped` required	integer	Subscriptions left out; retry tries them again

PriceChangeItem

Field	Type	Description
`subscription_id` required	string · uuid
`customer_external_id` required	string
`state` required	`scheduled` \| `applied` \| `withdrawn` \| `skipped`
`reason` required	string	Why it was skipped (as in PriceChangeSkipped); empty otherwise
`effective_time` required	string · date-time	The renewal the new price starts on; unset for a skipped one
`notify_time` required	string · date-time	When the customer's mail was queued; unset for a skipped one

PriceChangeSkipped

Field	Type	Description
`subscription_id` required	string · uuid
`customer_external_id` required	string
`reason` required	`renews_soon` \| `has_pending_change` \| `run_by_provider` \| `not_changeable` \| `customer_blocked`

SchedulePriceChangeResponse

Field	Type	Description
`scheduled` required	integer	Scheduled by this run
`scheduled_subscription_ids` required	array of string · uuid
`skipped` required	array of PriceChangeSkipped
`to_version` required	integer
`notice_days` required	integer
`price_change_id`	string	The price change this run made or continued; empty for a dry run when none is open
`already_scheduled`	integer	Scheduled by this price change before: not scheduled or mailed again

WithdrawPriceChangeResponse

Field	Type	Description
`price_change` required	PriceChange
`withdrawn` required	integer	How many waiting changes this call cancelled

price-changes

GET /v1/price-changes #

Parameters

Responses

GET /v1/price-changes/{id} #

Parameters

Responses

POST /v1/price-changes/{id}/retry #

Parameters

Responses

POST /v1/price-changes/{id}/withdraw #

Parameters

Responses

Models

Error

GetPriceChangeResponse

ListPriceChangesResponse

PriceChange

PriceChangeItem

PriceChangeSkipped

SchedulePriceChangeResponse

WithdrawPriceChangeResponse

GET `/v1/price-changes` #

GET `/v1/price-changes/{id}` #

POST `/v1/price-changes/{id}/retry` #

POST `/v1/price-changes/{id}/withdraw` #