> 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.

# Modify entitlement expiration

POST https://restapi.ordergroove.com/entitlements/{entitlement.public_id}/modify_expiration/
Content-Type: application/json

Modifies the expiration date of an entitlement. For the entitlement modified:

- `live` is updated to `true`
- An `EntitlementTransaction` is created
- If called on a meta-entitlement with renewal date correction enabled, existing orders for the resource move to the new expiration date
- An `entitlement.entitlements_expiration_modified` event is triggered upon successful modification

Reference: https://docs.ordergroove.com/reference/entitlements-service-api/entitlements/post-entitlements-modify-expiration

## Request

### Path parameters

- `entitlement.public_id` (string, required) — Public_id of entitlement

### Body (application/json)

- `expiration` (date, required) — New expiration date (YYYY-MM-DD) of entitlement. Cannot be past date.

## Response

### 200

- `results` (object, required)
  - `entitlement_transaction` (object, optional) — A transaction recorded against an entitlement.
    - `transaction_type` (string, required) — The type of transaction.
    - `public_id` (string, required) — Transaction ID.
    - `entitlement_public_id` (string, required) — ID of the entitlement the transaction was recorded against.
    - `merchant_user_id` (string, required) — Customer ID.
    - `resource_public_id` (string, required) — Resource ID.
    - `merchant_public_id` (string, required) — Merchant ID.
    - `transaction_initiation_time` (string, required) — Time the transaction was initiated (UTC).
    - `transaction_execution_time` (string, required, nullable) — Time the transaction was executed (UTC).
    - `source_action` (string, required) — The action that triggered the transaction.
    - `source_object` (string, required, nullable) — The type of object that triggered the transaction.
    - `source_object_id` (string, required, nullable) — ID of the object that triggered the transaction.
    - `access_type` (string, required, nullable) — The entitlement's access type at the time of the transaction.
    - `grace_period` (integer, required, nullable) — Grace period, in seconds.
    - `expiration` (string, required, nullable) — Expiration datetime (UTC).
    - `grace_period_expiration` (string, required, nullable) — Expiration datetime including the grace period (UTC).
  - `entitlement` (object, optional) — An entitlement granting a customer access to a resource.
    - `merchant` (string, required) — Merchant ID.
    - `public_id` (string, required) — Entitlement ID.
    - `merchant_user_id` (string, required) — Customer ID.
    - `initial_activation_date` (string, required, nullable) — Initial activation date (UTC).
    - `latest_activation_date` (string, required, nullable) — Latest activation date (UTC).
    - `grace_period` (integer, required, nullable) — Grace period, in seconds.
    - `live` (boolean, required) — Whether the resource this entitlement grants access to is currently accessible. Accounts for `grace_period`.
    - `access_type` (string, required) — The entitlement's access type.
    - `expiration` (string, required, nullable) — Entitlement access expiration date (UTC).
    - `created` (string, required) — Date the entitlement was created (UTC).
    - `last_updated` (string, required) — Date the entitlement was last updated (UTC).
    - `grantees` (list of object, required, nullable) — Grantees associated with the entitlement. `null` if there are none.
      - `external_id` (string, required) — The grantee's external ID.
      - `name` (string, required) — The grantee's name.
      - `created` (string, required) — Date the grantee was created (UTC).
      - `updated` (string, required) — Date the grantee was last updated (UTC).
    - `resource` (object, optional) — The resource this entitlement grants access to.
      - `public_id` (string, required) — Resource ID.
      - `merchant` (string, required) — Merchant ID.
      - `name` (string, required) — Resource name.
      - `external_resource_id` (string, required, nullable) — Merchant resource ID.
      - `identified_product_external_id` (string, required, nullable) — External ID of the Ordergroove product this resource is linked to for subscription renewal syncing. Present only when the resource is tied to a meta-entitlement; `null` otherwise.
      - `description` (string, required, nullable) — Resource description.
      - `image_url` (string, required, nullable) — Resource image URL.
      - `created` (string, required) — Date the resource was created (UTC).
      - `last_updated` (string, required) — Date the resource was last updated (UTC).
  - `renewal_correction` (object, optional) — Present only when the entitlement is a meta-entitlement with renewal date correction enabled. Reports the outcome of moving existing orders to the new expiration date.
    - `success` (boolean, required) — Whether the entire renewal correction succeeded.
    - `updated_order_ids` (list of string, optional) — IDs of orders whose renewal date was corrected. Present only if at least one order was corrected.
    - `failed_order_ids` (list of string, optional) — IDs of orders that failed renewal date correction. Present only if at least one order failed.
    - `message` (string, optional) — Explanation of any failure during the renewal correction attempt. Present only when relevant.

## Examples

**Request**

```json
{
  "expiration": "2023-01-15"
}
```

**Response**

```json
{
  "results": {
    "entitlement_transaction": {
      "transaction_type": "modify_expiration",
      "public_id": "71a591cb40be4985ab9ce2746329c865",
      "entitlement_public_id": "6bba77e50a244f818f32f17e2da5aed8",
      "merchant_user_id": "23773486874988",
      "resource_public_id": "450a64bf72024d99998f6c7541fefa42",
      "merchant_public_id": "80c9a167fb434fa0abe215c7f19a86cc",
      "transaction_initiation_time": "2026-03-11T18:51:45.520224856Z",
      "transaction_execution_time": "2026-03-11T18:51:45.520224856Z",
      "source_action": "api-call",
      "source_object": "user",
      "source_object_id": "dd0756ea-f502-4292-931e-b48f26677ef9_2026-03-11T18:51:45.520224856Z",
      "access_type": "time_based",
      "grace_period": 0,
      "expiration": "2028-03-01T23:59:59Z",
      "grace_period_expiration": "2028-03-01T23:59:59Z"
    },
    "entitlement": {
      "merchant": "80c9a167fb434fa0abe215c7f19a86cc",
      "public_id": "6bba77e50a244f818f32f17e2da5aed8",
      "merchant_user_id": "23773486874988",
      "initial_activation_date": null,
      "latest_activation_date": null,
      "grace_period": 0,
      "live": true,
      "access_type": "time_based",
      "expiration": "2028-03-01T23:59:59Z",
      "created": "2026-03-03T17:06:09.424Z",
      "last_updated": "2026-03-11T18:51:45.521796755Z",
      "grantees": null,
      "resource": {
        "public_id": "450a64bf72024d99998f6c7541fefa42",
        "merchant": "80c9a167fb434fa0abe215c7f19a86cc",
        "name": "Meta Plan Candidate 01",
        "external_resource_id": "52810769170796",
        "identified_product_external_id": null,
        "description": null,
        "image_url": null,
        "created": "2025-10-28T17:48:10.806Z",
        "last_updated": "2025-10-28T17:48:10.806Z"
      }
    },
    "renewal_correction": {
      "success": true,
      "updated_order_ids": [
        "d8dee1f287c4429b83ff54f438937d98"
      ]
    }
  }
}
```

**SDK Code**

```python OK
import requests

url = "https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/"

payload = { "expiration": "2023-01-15" }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript OK
const url = 'https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"expiration":"2023-01-15"}'
};

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

```go OK
package main

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

func main() {

	url := "https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/"

	payload := strings.NewReader("{\n  \"expiration\": \"2023-01-15\"\n}")

	req, _ := http.NewRequest("POST", 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(res)
	fmt.Println(string(body))

}
```

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

url = URI("https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expiration\": \"2023-01-15\"\n}"

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

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

HttpResponse<String> response = Unirest.post("https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/")
  .header("Content-Type", "application/json")
  .body("{\n  \"expiration\": \"2023-01-15\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/', [
  'body' => '{
  "expiration": "2023-01-15"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp OK
using RestSharp;

var client = new RestClient("https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"expiration\": \"2023-01-15\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift OK
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["expiration": "2023-01-15"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://restapi.ordergroove.com/entitlements/entitlement.public_id/modify_expiration/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```