Update a specific subscription

curl --request PUT \
  --url https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "billing_frequency": "monthly",
  "billing_interval": 1,
  "billing_limit": 123,
  "shipping_frequency": "monthly",
  "shipping_interval": 1,
  "shipping_limit": 123,
  "is_prepaid": false,
  "usage_based_billing": false,
  "usage_based_tiers": [
    {
      "up_to": 123,
      "price_per_unit": 123
    }
  ],
  "grace_period_days": 0,
  "is_cancellation_allowed": true,
  "days_until_cancellation_allowed": 3,
  "invoice_items": [
    {
      "product_id": "<string>",
      "variant_id": "<string>",
      "quantity": 123
    }
  ]
}
'

import requests

url = "https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}"

payload = {
    "command": "<string>",
    "billing_frequency": "monthly",
    "billing_interval": 1,
    "billing_limit": 123,
    "shipping_frequency": "monthly",
    "shipping_interval": 1,
    "shipping_limit": 123,
    "is_prepaid": False,
    "usage_based_billing": False,
    "usage_based_tiers": [
        {
            "up_to": 123,
            "price_per_unit": 123
        }
    ],
    "grace_period_days": 0,
    "is_cancellation_allowed": True,
    "days_until_cancellation_allowed": 3,
    "invoice_items": [
        {
            "product_id": "<string>",
            "variant_id": "<string>",
            "quantity": 123
        }
    ]
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    command: '<string>',
    billing_frequency: 'monthly',
    billing_interval: 1,
    billing_limit: 123,
    shipping_frequency: 'monthly',
    shipping_interval: 1,
    shipping_limit: 123,
    is_prepaid: false,
    usage_based_billing: false,
    usage_based_tiers: [{up_to: 123, price_per_unit: 123}],
    grace_period_days: 0,
    is_cancellation_allowed: true,
    days_until_cancellation_allowed: 3,
    invoice_items: [{product_id: '<string>', variant_id: '<string>', quantity: 123}]
  })
};

fetch('https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}', 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://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => '<string>',
    'billing_frequency' => 'monthly',
    'billing_interval' => 1,
    'billing_limit' => 123,
    'shipping_frequency' => 'monthly',
    'shipping_interval' => 1,
    'shipping_limit' => 123,
    'is_prepaid' => false,
    'usage_based_billing' => false,
    'usage_based_tiers' => [
        [
                'up_to' => 123,
                'price_per_unit' => 123
        ]
    ],
    'grace_period_days' => 0,
    'is_cancellation_allowed' => true,
    'days_until_cancellation_allowed' => 3,
    'invoice_items' => [
        [
                'product_id' => '<string>',
                'variant_id' => '<string>',
                'quantity' => 123
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}"

	payload := strings.NewReader("{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}")

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

	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.put("https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}"

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

{
  "message": "<string>",
  "success": true,
  "content": {
    "subscription": {
      "id": "<string>",
      "plan_id": "<string>",
      "plan_name": "<string>",
      "price": 123,
      "start_date": "2023-12-25",
      "end_date": "2023-12-25",
      "trial_days": 0,
      "trial_start_date": "2023-12-25",
      "trial_end_date": "2023-12-25",
      "next_billing_date": "2023-12-25",
      "last_payment_date": "2023-11-07T05:31:56Z",
      "pause_start_date": "2023-12-25",
      "pause_end_date": "2023-12-25",
      "billing_frequency": "monthly",
      "billing_interval": 1,
      "billing_limit": 123,
      "shipping_frequency": "monthly",
      "shipping_interval": 1,
      "shipping_limit": 123,
      "coupon_id": "<string>",
      "coupon_code": "<string>",
      "coupon_discount_percent": 0,
      "coupon_discount_amount": 0,
      "coupon_redemption_limit": 0,
      "is_prepaid": false,
      "usage_based_billing": true,
      "usage_based_tiers": [
        {
          "up_to": 123,
          "price_per_unit": 123
        }
      ],
      "grace_period_days": 0,
      "is_cancellation_allowed": true,
      "days_until_cancellation_allowed": 3,
      "currency": {
        "name": "<string>",
        "code": "<string>",
        "symbol": "<string>"
      },
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "invoice_items": [
        {
          "product_id": "<string>",
          "variant_id": "<string>",
          "product_name": "<string>",
          "variant_name": "<string>",
          "product_image_url": "<string>",
          "sku": "<string>",
          "quantity": 123,
          "listing_price": 123,
          "selling_price": 123,
          "tax_type": "<string>",
          "tax_rate": 123,
          "price_including_tax": true,
          "selling_price_excluding_tax": 123
        }
      ],
      "billing_address": {
        "first_name": "<string>",
        "last_name": "<string>",
        "country_code": "<string>",
        "phone": "<string>",
        "email": "<string>",
        "address_line1": "<string>",
        "address_line2": "<string>",
        "landmark": "<string>",
        "pincode": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "tax_identification_number": "<string>",
        "business_name": "<string>",
        "is_phone_verified": true,
        "is_email_verified": true,
        "id": "<string>",
        "is_default_billing": true,
        "is_default_shipping": true,
        "nickname": null
      },
      "shipping_address": {
        "first_name": "<string>",
        "last_name": "<string>",
        "country_code": "<string>",
        "phone": "<string>",
        "email": "<string>",
        "address_line1": "<string>",
        "address_line2": "<string>",
        "landmark": "<string>",
        "pincode": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "tax_identification_number": "<string>",
        "business_name": "<string>",
        "is_phone_verified": true,
        "is_email_verified": true,
        "id": "<string>",
        "is_default_billing": true,
        "is_default_shipping": true,
        "nickname": null
      }
    }
  }
}

{
  "message": "<string>",
  "success": true,
  "code": "<string>",
  "error": {}
}

{
  "message": "<string>",
  "success": false,
  "code": "<string>"
}

{
  "message": "<string>",
  "success": true,
  "code": "<string>"
}

PUT

subscriptions

{id}

Update a specific subscription

curl --request PUT \
  --url https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "billing_frequency": "monthly",
  "billing_interval": 1,
  "billing_limit": 123,
  "shipping_frequency": "monthly",
  "shipping_interval": 1,
  "shipping_limit": 123,
  "is_prepaid": false,
  "usage_based_billing": false,
  "usage_based_tiers": [
    {
      "up_to": 123,
      "price_per_unit": 123
    }
  ],
  "grace_period_days": 0,
  "is_cancellation_allowed": true,
  "days_until_cancellation_allowed": 3,
  "invoice_items": [
    {
      "product_id": "<string>",
      "variant_id": "<string>",
      "quantity": 123
    }
  ]
}
'

import requests

url = "https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}"

payload = {
    "command": "<string>",
    "billing_frequency": "monthly",
    "billing_interval": 1,
    "billing_limit": 123,
    "shipping_frequency": "monthly",
    "shipping_interval": 1,
    "shipping_limit": 123,
    "is_prepaid": False,
    "usage_based_billing": False,
    "usage_based_tiers": [
        {
            "up_to": 123,
            "price_per_unit": 123
        }
    ],
    "grace_period_days": 0,
    "is_cancellation_allowed": True,
    "days_until_cancellation_allowed": 3,
    "invoice_items": [
        {
            "product_id": "<string>",
            "variant_id": "<string>",
            "quantity": 123
        }
    ]
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    command: '<string>',
    billing_frequency: 'monthly',
    billing_interval: 1,
    billing_limit: 123,
    shipping_frequency: 'monthly',
    shipping_interval: 1,
    shipping_limit: 123,
    is_prepaid: false,
    usage_based_billing: false,
    usage_based_tiers: [{up_to: 123, price_per_unit: 123}],
    grace_period_days: 0,
    is_cancellation_allowed: true,
    days_until_cancellation_allowed: 3,
    invoice_items: [{product_id: '<string>', variant_id: '<string>', quantity: 123}]
  })
};

fetch('https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}', 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://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => '<string>',
    'billing_frequency' => 'monthly',
    'billing_interval' => 1,
    'billing_limit' => 123,
    'shipping_frequency' => 'monthly',
    'shipping_interval' => 1,
    'shipping_limit' => 123,
    'is_prepaid' => false,
    'usage_based_billing' => false,
    'usage_based_tiers' => [
        [
                'up_to' => 123,
                'price_per_unit' => 123
        ]
    ],
    'grace_period_days' => 0,
    'is_cancellation_allowed' => true,
    'days_until_cancellation_allowed' => 3,
    'invoice_items' => [
        [
                'product_id' => '<string>',
                'variant_id' => '<string>',
                'quantity' => 123
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}"

	payload := strings.NewReader("{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}")

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

	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.put("https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging.api.commercengine.io/api/v1/{store_id}/storefront/subscriptions/{id}")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"<string>\",\n  \"billing_frequency\": \"monthly\",\n  \"billing_interval\": 1,\n  \"billing_limit\": 123,\n  \"shipping_frequency\": \"monthly\",\n  \"shipping_interval\": 1,\n  \"shipping_limit\": 123,\n  \"is_prepaid\": false,\n  \"usage_based_billing\": false,\n  \"usage_based_tiers\": [\n    {\n      \"up_to\": 123,\n      \"price_per_unit\": 123\n    }\n  ],\n  \"grace_period_days\": 0,\n  \"is_cancellation_allowed\": true,\n  \"days_until_cancellation_allowed\": 3,\n  \"invoice_items\": [\n    {\n      \"product_id\": \"<string>\",\n      \"variant_id\": \"<string>\",\n      \"quantity\": 123\n    }\n  ]\n}"

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

{
  "message": "<string>",
  "success": true,
  "content": {
    "subscription": {
      "id": "<string>",
      "plan_id": "<string>",
      "plan_name": "<string>",
      "price": 123,
      "start_date": "2023-12-25",
      "end_date": "2023-12-25",
      "trial_days": 0,
      "trial_start_date": "2023-12-25",
      "trial_end_date": "2023-12-25",
      "next_billing_date": "2023-12-25",
      "last_payment_date": "2023-11-07T05:31:56Z",
      "pause_start_date": "2023-12-25",
      "pause_end_date": "2023-12-25",
      "billing_frequency": "monthly",
      "billing_interval": 1,
      "billing_limit": 123,
      "shipping_frequency": "monthly",
      "shipping_interval": 1,
      "shipping_limit": 123,
      "coupon_id": "<string>",
      "coupon_code": "<string>",
      "coupon_discount_percent": 0,
      "coupon_discount_amount": 0,
      "coupon_redemption_limit": 0,
      "is_prepaid": false,
      "usage_based_billing": true,
      "usage_based_tiers": [
        {
          "up_to": 123,
          "price_per_unit": 123
        }
      ],
      "grace_period_days": 0,
      "is_cancellation_allowed": true,
      "days_until_cancellation_allowed": 3,
      "currency": {
        "name": "<string>",
        "code": "<string>",
        "symbol": "<string>"
      },
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "invoice_items": [
        {
          "product_id": "<string>",
          "variant_id": "<string>",
          "product_name": "<string>",
          "variant_name": "<string>",
          "product_image_url": "<string>",
          "sku": "<string>",
          "quantity": 123,
          "listing_price": 123,
          "selling_price": 123,
          "tax_type": "<string>",
          "tax_rate": 123,
          "price_including_tax": true,
          "selling_price_excluding_tax": 123
        }
      ],
      "billing_address": {
        "first_name": "<string>",
        "last_name": "<string>",
        "country_code": "<string>",
        "phone": "<string>",
        "email": "<string>",
        "address_line1": "<string>",
        "address_line2": "<string>",
        "landmark": "<string>",
        "pincode": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "tax_identification_number": "<string>",
        "business_name": "<string>",
        "is_phone_verified": true,
        "is_email_verified": true,
        "id": "<string>",
        "is_default_billing": true,
        "is_default_shipping": true,
        "nickname": null
      },
      "shipping_address": {
        "first_name": "<string>",
        "last_name": "<string>",
        "country_code": "<string>",
        "phone": "<string>",
        "email": "<string>",
        "address_line1": "<string>",
        "address_line2": "<string>",
        "landmark": "<string>",
        "pincode": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "tax_identification_number": "<string>",
        "business_name": "<string>",
        "is_phone_verified": true,
        "is_email_verified": true,
        "id": "<string>",
        "is_default_billing": true,
        "is_default_shipping": true,
        "nickname": null
      }
    }
  }
}

{
  "message": "<string>",
  "success": true,
  "code": "<string>",
  "error": {}
}

{
  "message": "<string>",
  "success": false,
  "code": "<string>"
}

{
  "message": "<string>",
  "success": true,
  "code": "<string>"
}

Path Parameters

string

required

subscription id

Body

application/json

UpdatePhysicalProductSubscription
UpdateDigitalProductSubscription
PauseSubscription
RevokeSubscription

command

string

required

Allowed value: "update"

billing_frequency

enum<string>

Available options:

monthly

billing_interval

integer

default:1

billing_limit

integer | null

null means there is no limit on number of invoices generated. If specified, then subscription will be revoked automatically after billing limit is reached.

shipping_frequency

enum<string>

Available options:

monthly

shipping_interval

integer

default:1

shipping_limit

integer | null

null means there is no limit on number of deliveries completed. If specified, then subscription will be revoked automatically after shipping limit is reached.

is_prepaid

boolean

default:false

Refers to a pricing model where customers are charged based on their actual usage of a service. Usage based billing works for digital products.

usage_based_billing

boolean

default:false

Refers to a pricing model where customers are charged based on their actual usage of a service. Usage based billing works for digital products.

usage_based_tiers

object[]

Refers to a pricing structure where customers are charged based on their usage, but the cost per unit of usage decreases or changes as they move into higher usage levels.

Show child attributes

grace_period_days

integer

default:0

The number of days after a failed payment to retry before canceling.

is_cancellation_allowed

boolean

default:true

Indcates whether the next billing cancellation is allowed or not.

days_until_cancellation_allowed

integer

default:3

Specifies the number of days the customer has to cancel before the next billing.

invoice_items

SubscriptionInvoiceItem · object[]

Show child attributes

Response

message

string

required

success

boolean

required

content

object

required

Show child attributes

Retrieve subscription details

Create anonymous session

Introduction

🛍️ Commerce

🙋 Customers

🎟️ Engagement & Retention

🧰 Utilities

POS

Store Config

Marketplace

🔔 Webhooks

Update a specific subscription

Path Parameters

Body

Response