Create migration

curl --request POST \
  --url https://api.withorb.com/v1/migrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target_plan_version_number": 123,
  "plan_id": "<string>",
  "external_plan_id": "<string>",
  "effective_date": "2023-12-25",
  "included_subscription_ids": [
    "<string>"
  ],
  "excluded_subscription_ids": [
    "<string>"
  ],
  "statuses": [
    "active"
  ],
  "plan_version_numbers": [
    123
  ],
  "in_trial": true,
  "allow_invoice_credit_or_void": true,
  "can_defer_billing": false,
  "reason": "<string>"
}
'

import requests

url = "https://api.withorb.com/v1/migrations"

payload = {
    "target_plan_version_number": 123,
    "plan_id": "<string>",
    "external_plan_id": "<string>",
    "effective_date": "2023-12-25",
    "included_subscription_ids": ["<string>"],
    "excluded_subscription_ids": ["<string>"],
    "statuses": ["active"],
    "plan_version_numbers": [123],
    "in_trial": True,
    "allow_invoice_credit_or_void": True,
    "can_defer_billing": False,
    "reason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    target_plan_version_number: 123,
    plan_id: '<string>',
    external_plan_id: '<string>',
    effective_date: '2023-12-25',
    included_subscription_ids: ['<string>'],
    excluded_subscription_ids: ['<string>'],
    statuses: ['active'],
    plan_version_numbers: [123],
    in_trial: true,
    allow_invoice_credit_or_void: true,
    can_defer_billing: false,
    reason: '<string>'
  })
};

fetch('https://api.withorb.com/v1/migrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/migrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target_plan_version_number' => 123,
    'plan_id' => '<string>',
    'external_plan_id' => '<string>',
    'effective_date' => '2023-12-25',
    'included_subscription_ids' => [
        '<string>'
    ],
    'excluded_subscription_ids' => [
        '<string>'
    ],
    'statuses' => [
        'active'
    ],
    'plan_version_numbers' => [
        123
    ],
    'in_trial' => true,
    'allow_invoice_credit_or_void' => true,
    'can_defer_billing' => false,
    'reason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/migrations"

	payload := strings.NewReader("{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/migrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/migrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "plan_id": "<string>",
  "effective_time": "2023-12-25",
  "status": "not_started",
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "target_plan_version_number": 123
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

POST

migrations

Create migration

curl --request POST \
  --url https://api.withorb.com/v1/migrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target_plan_version_number": 123,
  "plan_id": "<string>",
  "external_plan_id": "<string>",
  "effective_date": "2023-12-25",
  "included_subscription_ids": [
    "<string>"
  ],
  "excluded_subscription_ids": [
    "<string>"
  ],
  "statuses": [
    "active"
  ],
  "plan_version_numbers": [
    123
  ],
  "in_trial": true,
  "allow_invoice_credit_or_void": true,
  "can_defer_billing": false,
  "reason": "<string>"
}
'

import requests

url = "https://api.withorb.com/v1/migrations"

payload = {
    "target_plan_version_number": 123,
    "plan_id": "<string>",
    "external_plan_id": "<string>",
    "effective_date": "2023-12-25",
    "included_subscription_ids": ["<string>"],
    "excluded_subscription_ids": ["<string>"],
    "statuses": ["active"],
    "plan_version_numbers": [123],
    "in_trial": True,
    "allow_invoice_credit_or_void": True,
    "can_defer_billing": False,
    "reason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    target_plan_version_number: 123,
    plan_id: '<string>',
    external_plan_id: '<string>',
    effective_date: '2023-12-25',
    included_subscription_ids: ['<string>'],
    excluded_subscription_ids: ['<string>'],
    statuses: ['active'],
    plan_version_numbers: [123],
    in_trial: true,
    allow_invoice_credit_or_void: true,
    can_defer_billing: false,
    reason: '<string>'
  })
};

fetch('https://api.withorb.com/v1/migrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/migrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target_plan_version_number' => 123,
    'plan_id' => '<string>',
    'external_plan_id' => '<string>',
    'effective_date' => '2023-12-25',
    'included_subscription_ids' => [
        '<string>'
    ],
    'excluded_subscription_ids' => [
        '<string>'
    ],
    'statuses' => [
        'active'
    ],
    'plan_version_numbers' => [
        123
    ],
    'in_trial' => true,
    'allow_invoice_credit_or_void' => true,
    'can_defer_billing' => false,
    'reason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/migrations"

	payload := strings.NewReader("{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/migrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/migrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target_plan_version_number\": 123,\n  \"plan_id\": \"<string>\",\n  \"external_plan_id\": \"<string>\",\n  \"effective_date\": \"2023-12-25\",\n  \"included_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"excluded_subscription_ids\": [\n    \"<string>\"\n  ],\n  \"statuses\": [\n    \"active\"\n  ],\n  \"plan_version_numbers\": [\n    123\n  ],\n  \"in_trial\": true,\n  \"allow_invoice_credit_or_void\": true,\n  \"can_defer_billing\": false,\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "plan_id": "<string>",
  "effective_time": "2023-12-25",
  "status": "not_started",
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "target_plan_version_number": 123
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Body

application/json

target_plan_version_number

integer

required

The plan version to migrate subscriptions to. It can't be a draft version.

effective_time

enum<string>

required

When the migration takes effect: 'immediately', 'requested_date' on effective_date, 'start_of_term' or 'end_of_term' for the start or end of each subscription's current billing period, or 'start_of_invoice' or 'end_of_invoice' for the start of its current or next invoice.

Available options:

immediately,

requested_date,

start_of_term,

end_of_term,

start_of_invoice,

end_of_invoice

plan_id

string | null

The plan whose subscriptions to migrate. Exactly one of plan_id and external_plan_id is required.

external_plan_id

string | null

The external ID of the plan whose subscriptions to migrate.

effective_date

string<date> | null

The date the migration takes effect, at midnight in each customer's timezone. Required when effective_time is requested_date, and not allowed otherwise.

included_subscription_ids

string[] | null

Migrate only these subscriptions. When set, the filters below are ignored.

Required array length: 1 - 250 elements

excluded_subscription_ids

string[] | null

Leave these subscriptions out. Can't be combined with included_subscription_ids.

Required array length: 1 - 250 elements

statuses

enum<string>[]

Migrate subscriptions with these statuses. Defaults to active subscriptions.

Minimum array length: 1

Available options:

active,

upcoming

plan_version_numbers

integer[] | null

Migrate only subscriptions currently on these plan versions.

Minimum array length: 1

in_trial

boolean | null

true migrates only subscriptions in a trial, false only subscriptions not in a trial.

allow_invoice_credit_or_void

boolean

default:true

When false, a subscription whose migration would void an issued invoice or create a credit note fails instead.

can_defer_billing

boolean

default:false

When true, an in-arrears price the migration ends mid-cycle bills its final line item on the next scheduled invoice instead of on its end date.

reason

string | null

Why the migration was created.

Maximum string length: 500

Response

Created

A migration moves a plan's subscriptions onto one of the plan's versions. Each subscription is migrated asynchronously, either immediately or at a scheduled time, and the migration reports its overall status as it progresses.

string

required

Unique identifier for this plan version change.

plan_id

string

required

The ID of the plan being migrated.

effective_time

required

When the migration takes effect. Can be a specific date/time, 'start_of_term' or 'end_of_term' when scheduled to be at the start or end of the current billing period, or 'start_of_invoice' or 'end_of_invoice' when scheduled to be at the start of the current or next invoice.

status

enum<string>

required

Current status of the migration: 'not_started', 'in_progress', 'completed', 'action_needed', or 'canceled'.

Available options:

not_started,

in_progress,

completed,

action_needed,

canceled

started_at

string<date-time> | null

required

When Orb began migrating the plan's subscriptions. Null if the migration has not begun, or was canceled before it began.

ended_at

string<date-time> | null

required

When the migration completed or was canceled, or null if it is still in progress.

target_plan_version_number

integer

required

The plan version subscriptions are migrated to.

API documentation

Webhooks

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

LicenseType

License

Metric

Migration

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Webhook endpoint

Create migration

Authorizations

Body

Response