> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server.

# Upgrade Subscription To Prepaid

PATCH https://restapi.ordergroove.com/subscriptions/{subscription_id}/upgrade_to_prepaid/
Content-Type: application/json

Upgrades a pay-as-you-go subscription to a prepaid subscription.

Returns `400`, with the reason in `detail`, when the merchant doesn't have prepaid subscriptions enabled, the subscription is already prepaid or isn't `live`, `orders_per_billing` is missing or less than `2`, or the subscription's product isn't prepaid-eligible (in the `prepaid` eligibility product group).

The upgraded subscription starts with `prepaid_orders_remaining` at `0`, so its next order is a renewal. That order is repriced right away to `orders_per_billing` times the unit price, and the customer pays for the full prepaid cycle when it's placed. Because the customer never receives an order they haven't paid for, the upgrade can be offered directly in the Subscription Manager. If `renewal_behavior` is omitted, the merchant's default renewal behavior applies, or `autorenew` if none is set.

Reference: https://docs.ordergroove.com/reference/rest-rpc-api/subscriptions/upgrade-to-prepaid-subscription

## Authentication

- `x-api-key` header (required) — Application API Scope — server-to-server, sent in the `x-api-key` header. See [Authentication](/api-reference/authentication).
- `authorization` header (required) — Storefront API Scope — client-side, scoped to one customer, sent as a signature in the `authorization` header. See [Authentication](/api-reference/authentication).

## Request

### Path parameters

- `subscription_id` (string, required) — Unique subscription ID

### Body (application/json)

This endpoint expects an object.

- `orders_per_billing` (integer, required) — Number of orders per prepaid billing cycle. Must be at least `2`.
- `renewal_behavior` (enum, optional, default: autorenew)
  - Allowed values: `autorenew`, `cancel`, `downgrade`
- `offer` (string, optional) — Public ID of the offer to associate the subscription with after the upgrade, or `live` for the merchant's currently live offer. When omitted, the subscription keeps its current offer.

## Response

### 200

200

- `customer` (string, optional)
- `merchant` (string, optional)
- `product` (string, optional)
- `payment` (string, optional)
- `shipping_address` (string, optional, nullable)
- `offer` (string, optional, nullable)
- `offer_profile_public_id` (string, optional, nullable) — Public ID of the offer profile the subscription's offer belongs to. Returned only by List and Retrieve.
- `subscription_type` (string, optional)
- `raw_subscription_type` (string, optional) — The subscription type as stored. `subscription_type` reports `IU replenishment` and `CSA replenishment` as `replenishment`; this field keeps the original value.
- `components` (list of SubscriptionComponentsItems, optional) — Bundle components. Each has `product`; `public_id` and `quantity` are returned only when the merchant has multi-item bundles enabled.
- `extra_data` (SubscriptionExtraData, optional) — Custom data stored on the subscription, as a JSON object. `{}` when the subscription has none. Ordergroove and your integrations can store their own keys here.
- `public_id` (string, optional)
- `product_attribute` (integer, optional, nullable)
- `quantity` (integer, optional)
- `price` (string, optional, nullable)
- `frequency_days` (integer, optional)
- `reminder_days` (integer, optional)
- `every` (integer, optional)
- `every_period` (integer, optional)
- `start_date` (string, optional)
- `cancelled` (string, optional, nullable)
- `cancel_reason` (string, optional, nullable)
- `cancel_reason_code` (integer, optional, nullable)
- `iteration` (integer, optional, nullable)
- `sequence` (integer, optional, nullable)
- `session_id` (string, optional)
- `merchant_order_id` (string, optional, nullable)
- `customer_rep` (integer, optional, nullable)
- `club` (integer, optional, nullable)
- `created` (string, optional)
- `updated` (string, optional)
- `live` (boolean, optional)
- `external_id` (string, optional, nullable)
- `currency_code` (string, optional, nullable) — Three-letter ISO currency code.
- `queued_actions` (list of SubscriptionQueuedActionsItems, optional) — Pending queued actions, in order. Returned only when the merchant has queued actions enabled; empty when the subscription isn't live or has none.
- `prepaid_subscription_context` (SubscriptionPrepaidSubscriptionContext, optional, nullable) — Prepaid details. Returned only when the merchant has prepaid subscriptions enabled; `null` when this subscription isn't prepaid.
- `grantees` (list of Grantee, optional) — List of grantees associated with the subscription. Omitted if the subscription has no grantees.
- `free_trial_subscription_context` (FreeTrialSubscriptionContext, optional) — Present only if the subscription has a free trial context (i.e. it was created for a product with a free trial configured); omitted otherwise.

## Errors

### 400 Bad Request Error

400

## Types

### SubscriptionComponentsItems

- `public_id` (string, optional)
- `quantity` (integer, optional)
- `product` (string, optional)

### SubscriptionExtraData

Custom data stored on the subscription, as a JSON object. `{}` when the subscription has none. Ordergroove and your integrations can store their own keys here.

- `shopify_contract_id` (string, optional) — Shopify subscriptions only. The ID of the Shopify subscription contract the subscription is linked to. Changing it links the subscription to a different contract.

### SubscriptionQueuedActionsItems

- `public_id` (string, optional)
- `ordinal` (integer, optional)
- `index` (integer, optional) — Position relative to the first pending action, starting at 0.
- `date` (string, optional, nullable) — Date the action applies, in ISO 8601 format.
- `skip` (boolean, optional) — Whether the action is set to skip.

### SubscriptionPrepaidSubscriptionContext

Prepaid details. Returned only when the merchant has prepaid subscriptions enabled; `null` when this subscription isn't prepaid.

- `prepaid_orders_remaining` (integer, optional)
- `prepaid_orders_per_billing` (integer, optional)
- `renewal_behavior` (enum, optional)
  - Allowed values: `cancel`, `autorenew`, `downgrade`
- `last_renewal_revenue` (double, optional)
- `prepaid_origin_merchant_order_id` (string, optional, nullable)

### Grantee

- `external_id` (string, required) — External ID of the grantee
- `name` (string, required) — Name of the grantee

### FreeTrialSubscriptionContext

Present only if the subscription has a free trial context (i.e. it was created for a product with a free trial configured); omitted otherwise.

- `product` (string, required) — External product ID of the product the free trial applies to
- `days` (integer, required) — Number of days configured for the free trial
- `conversion_item` (string, required, nullable) — Public ID of the associated conversion item, or null if not applicable
- `expiration` (string, required) — Free trial expiration timestamp, in ISO 8601 format with no timezone offset
- `is_in_free_trial` (boolean, required) — Whether the subscription is still within its free trial period

## Examples

**Request**

```json
{
  "orders_per_billing": 1
}
```

**Response**

```json
{
  "customer": "00026001",
  "merchant": "ac4f7938383a11e89ecbbc764e1107f2",
  "product": "0070000693",
  "payment": "070001bc02fd11e99542bc764e1043b0",
  "shipping_address": "66c25cd0564011e9abc5bc764e107990",
  "offer": "a748aa648ac811e8af3bbc764e106cf4",
  "subscription_type": "replenishment",
  "raw_subscription_type": "replenishment",
  "components": [],
  "extra_data": {
    "shopify_contract_id": "gid://shopify/SubscriptionContract/2287823"
  },
  "public_id": "607daa2accc811e88516bc764e106cf4",
  "product_attribute": null,
  "quantity": 1,
  "price": null,
  "frequency_days": 30,
  "reminder_days": 4,
  "every": 1,
  "every_period": 3,
  "start_date": "2023-05-30",
  "cancelled": null,
  "cancel_reason": null,
  "cancel_reason_code": null,
  "iteration": null,
  "sequence": null,
  "session_id": "ac4f7938383a11e89ecbbc764e1107f2.896371.1539022086",
  "merchant_order_id": "#1144",
  "customer_rep": null,
  "club": null,
  "created": "2023-05-30 13:20:41",
  "updated": "2023-10-03 10:22:11",
  "live": true,
  "external_id": "2287823",
  "currency_code": "USD",
  "queued_actions": [],
  "prepaid_subscription_context": {
    "prepaid_orders_remaining": 0,
    "prepaid_orders_per_billing": 6,
    "renewal_behavior": "autorenew",
    "last_renewal_revenue": 0,
    "prepaid_origin_merchant_order_id": null
  }
}
```

**SDK Code**

```python Result
import requests

url = "https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/"

payload = { "orders_per_billing": 1 }
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript Result
const url = 'https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/';
const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"orders_per_billing":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Result
package main

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

func main() {

	url := "https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/"

	payload := strings.NewReader("{\n  \"orders_per_billing\": 1\n}")

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

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Result
require 'uri'
require 'net/http'

url = URI("https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/")

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

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orders_per_billing\": 1\n}"

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

```java Result
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orders_per_billing\": 1\n}")
  .asString();
```

```php Result
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/', [
  'body' => '{
  "orders_per_billing": 1
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Result
using RestSharp;

var client = new RestClient("https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/");
var request = new RestRequest(Method.PATCH);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"orders_per_billing\": 1\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Result
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["orders_per_billing": 1] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://restapi.ordergroove.com/subscriptions/subscription_id/upgrade_to_prepaid/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```