Service Actions v2

A ServiceAction represents a recurring, automated action that can be applied as part of a subscription.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/service_actions

GET/v2/billing/service_actions/:id

The ServiceAction object

Attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

The ServiceAction object

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

createServiceAction v2

Create a ServiceAction object.

Learn more about calling API v2 endpoints.

Parameters

service_intervalenumRequired
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countintegerRequired
The length of the interval for assessing service.

typeenumRequired
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

credit_grantobject
Details for the credit grant. Required if type is “credit_grant”.

credit_grant_per_tenantobject
Details for the credit grant per tenant. Required if type is “credit_grant_per_tenant”.

lookup_keystring
An internal key you can use to search for this service action. Maximum length of 200 characters.

Returns

Response attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

Error Codes

400array_must_not_be_empty

Returned by ServiceAction API when the price type is invalid.

400billable_item_not_metered

Returned by ServiceAction API when the billable item is not a metered_item.

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

400service_action_type_invalid

Returned by ServiceAction API when the type is invalid.

404billable_item_not_found

Returned when the provided billable_item ID cannot be found.

404custom_pricing_unit_not_found

Returned by CustomPricingUnit API when the custom pricing unit is not found.

404license_fee_not_found

Returned when the provided license_fee ID cannot be found.

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

POST /v2/billing/service_actions

Server-side language

curl -X POST https://api.stripe.com/v2/billing/service_actions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "service_interval": "day",
    "service_interval_count": 4242,
    "type": "credit_grant"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

retrieveServiceAction v2

Retrieve a ServiceAction object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Service Action.

Returns

Response attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

Error Codes

404service_action_not_found

Returned by ServiceAction API when the service action is not found.

GET /v2/billing/service_actions/:id

Server-side language

curl https://api.stripe.com/v2/billing/service_actions/REPLACE ME \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

Rate Cards v2

A RateCard describes usage-based pricing. To bill a customer using a RateCard, create a RateCardSubscription which links it to the corresponding Cadence.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/rate_cards

POST/v2/billing/rate_cards/:id/rates

POST/v2/billing/rate_cards/:id

GET/v2/billing/rate_cards/:id

GET/v2/billing/rate_cards/:id/rates/:id

GET/v2/billing/rate_cards/:id/versions/:id

GET/v2/billing/rate_cards/:id/rates

GET/v2/billing/rate_cards

GET/v2/billing/rate_cards/:id/versions

DELETE/v2/billing/rate_cards/:id/rates/:id