Zum Hauptinhalt springen
POST
/
product-group-memberships
/
{id}
/
apply
cURL
curl -X POST \
 /product-group-memberships/{id}/apply \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --data '{"subscriptionItem": "item-uuid", "selectedPricePlan": "plan-uuid", "quantity": 1}'
{
  "subscriptionItem": {
    "id": "01F9ZQZJZJQZJZJZJZJZJZJZJZ",
    "parent": "<unknown>",
    "plan": {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
      },
      "code": "basic-m2023",
      "originProduct": {
        "type": "product",
        "measurement": {
          "unit": {
            "id": {},
            "name": "Stück"
          },
          "code": "users",
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "description": "The number of users.",
          "aggregationType": "sum",
          "fairBilling": true,
          "type": "recurring"
        },
        "taxGroup": {},
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "invoiceVisibility": "always",
        "costCentre": {},
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "draft",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    },
    "measurementValues": [
      {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "measurement": {
          "unit": {
            "id": {},
            "name": "Stück"
          },
          "code": "users",
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "description": "The number of users.",
          "aggregationType": "sum",
          "fairBilling": true,
          "type": "recurring"
        },
        "quantity": 1,
        "measuredAt": "2021-01-01T00:00:00+00:00"
      }
    ],
    "billing": {
      "lastBilledAt": "2023-11-07T05:31:56Z",
      "lastBilledTo": "2023-11-07T05:31:56Z",
      "lastBilledFrom": "2023-11-07T05:31:56Z",
      "nextBillingAt": "2023-11-07T05:31:56Z",
      "billingInterval": "1M"
    },
    "name": "Fitness M",
    "description": "Everything included",
    "furtherInformation": "Additional agreements: The contract includes a free drink flatrate.",
    "pricePlan": {
      "type": "flat_fee",
      "price": {
        "amount": 123,
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00",
        "tenantId": "<string>"
      },
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "internalName": "Exclusive pricing for partners.",
      "status": "active",
      "applyTrial": true,
      "payInAdvance": true,
      "proRata": true,
      "freeUnits": 1,
      "billingInterval": "1M",
      "showPricePerInterval": "1M",
      "custom": true,
      "charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "inUse": true
    },
    "status": "active",
    "product": {
      "type": "product",
      "measurement": {
        "unit": {
          "id": {},
          "name": "Stück"
        },
        "code": "users",
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "description": "The number of users.",
        "aggregationType": "sum",
        "fairBilling": true,
        "type": "recurring"
      },
      "taxGroup": {},
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "invoiceVisibility": "always",
      "costCentre": {},
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    },
    "appliedDiscounts": [
      {
        "id": "<string>",
        "coupon": {
          "code": "10OFF",
          "name": "10% off",
          "type": "percentage",
          "frequency": "limited",
          "id": "<string>",
          "percentage": 10,
          "fixedAmount": {},
          "frequencyInterval": 3,
          "maxRedemptionsPerCustomer": "null",
          "maxRedemptions": "null",
          "expiresAt": "null",
          "limitedToPlans": [
            {
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "family": {
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
              },
              "code": "basic-m2023",
              "originProduct": {
                "type": "product",
                "measurement": {
                  "unit": {
                    "id": {},
                    "name": "Stück"
                  },
                  "code": "users",
                  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                  "description": "The number of users.",
                  "aggregationType": "sum",
                  "fairBilling": true,
                  "type": "recurring"
                },
                "taxGroup": {},
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "name": "Basic",
                "description": "For small teams.",
                "internalName": "Basic (Weekly)",
                "invoiceVisibility": "always",
                "costCentre": {},
                "customFields": {
                  "field1": "value1",
                  "field2": "value2"
                }
              },
              "allowCheckout": true,
              "status": "draft",
              "createdAt": "2023-11-07T05:31:56Z",
              "name": "<string>",
              "description": "<string>"
            }
          ],
          "excludedFromPlans": [
            {
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "family": {
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
              },
              "code": "basic-m2023",
              "originProduct": {
                "type": "product",
                "measurement": {
                  "unit": {
                    "id": {},
                    "name": "Stück"
                  },
                  "code": "users",
                  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                  "description": "The number of users.",
                  "aggregationType": "sum",
                  "fairBilling": true,
                  "type": "recurring"
                },
                "taxGroup": {},
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "name": "Basic",
                "description": "For small teams.",
                "internalName": "Basic (Weekly)",
                "invoiceVisibility": "always",
                "costCentre": {},
                "customFields": {
                  "field1": "value1",
                  "field2": "value2"
                }
              },
              "allowCheckout": true,
              "status": "draft",
              "createdAt": "2023-11-07T05:31:56Z",
              "name": "<string>",
              "description": "<string>"
            }
          ],
          "limitedToProducts": [
            {
              "type": "product",
              "measurement": {
                "unit": {
                  "id": {},
                  "name": "Stück"
                },
                "code": "users",
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "description": "The number of users.",
                "aggregationType": "sum",
                "fairBilling": true,
                "type": "recurring"
              },
              "taxGroup": {},
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "name": "Basic",
              "description": "For small teams.",
              "internalName": "Basic (Weekly)",
              "invoiceVisibility": "always",
              "costCentre": {},
              "customFields": {
                "field1": "value1",
                "field2": "value2"
              }
            }
          ],
          "excludedFromProducts": [
            {
              "type": "product",
              "measurement": {
                "unit": {
                  "id": {},
                  "name": "Stück"
                },
                "code": "users",
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "description": "The number of users.",
                "aggregationType": "sum",
                "fairBilling": true,
                "type": "recurring"
              },
              "taxGroup": {},
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "name": "Basic",
              "description": "For small teams.",
              "internalName": "Basic (Weekly)",
              "invoiceVisibility": "always",
              "costCentre": {},
              "customFields": {
                "field1": "value1",
                "field2": "value2"
              }
            }
          ],
          "isEnabled": true,
          "reedemptions": true
        },
        "status": "active",
        "discount": {
          "name": "10% off",
          "type": "percentage",
          "frequency": "limited",
          "percentage": 10,
          "fixedAmount": {},
          "frequencyInterval": 3
        },
        "appliedIntervals": 1
      }
    ],
    "periods": [
      {
        "id": "<string>",
        "contractPeriodCount": 123,
        "contractPeriod": {},
        "cancellationPeriod": {},
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "activatedAt": "2021-01-01T00:00:00+00:00",
    "type": "addon",
    "currentMeasurementValue": {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "measurement": {
        "unit": {
          "id": {},
          "name": "Stück"
        },
        "code": "users",
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "description": "The number of users.",
        "aggregationType": "sum",
        "fairBilling": true,
        "type": "recurring"
      },
      "quantity": 1,
      "measuredAt": "2021-01-01T00:00:00+00:00"
    },
    "inheritedPeriod": true
  },
  "creditNote": {
    "id": "<string>",
    "number": "<string>",
    "amount": 123
  }
}
Change the tier (membership) of a subscription item to perform an upgrade or downgrade.

​
Flow

  1. Get available options via GET /subscription-items/{id}/change-options
  2. Select a tier from the options
  3. Execute the tier change using this endpoint

​
Request Parameters

ParameterRequiredDescription
subscriptionItemYesUUID of the subscription item to change
selectedPricePlanNoUUID of the price plan. Only required if the tier has multiple price plans configured. In most cases, each tier has a single price plan and this field can be omitted.
quantityNoNew quantity. Only applied if the tier allows quantity changes.
sendInvoiceEmailNoSend credit note via email (default: true)

​
Response

Returns the updated subscription item and any created credit note.

Implementation Guide

Complete guide for implementing self-service upgrades

Autorisierungen

​
Authorization
string
header
erforderlich

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Pfadparameter

​
id
string
erforderlich

ProductGroupMembership identifier

Body

application/json
​
subscriptionItem
string
erforderlich

UUID of the subscription item to change

​
selectedPricePlan
string

UUID of the selected price plan (optional if only one available)

​
quantity
integer

New quantity (optional)

Beispiel:

1

​
sendInvoiceEmail
boolean
Standard:true

Whether to send credit note via email

Antwort

Membership applied successfully

Result of applying a product group membership

​
subscriptionItem
object
​
creditNote
object