Update a subscription

PUT 
/subscriptions/subscriptions/:subscription_uuid

Updates a subscription. For example, a subscriber can switch from one plan to another in a subscription.

Request

Path Parameters

subscription_uuid UUIDrequired

The unique identifier of the subscription.

application/json

Body

data SubscriptionUpdaterequired

id UUID (string)required

The unique identifier.

type SubscriptionType (string)required

Possible values: [subscription]

attributes SubscriptionUpdateAttributesrequired

plan_id

address_id UUIDnullable

payment_authority object

oneOf

PaymentAuthorityStripe

type stringrequired

Possible values: [elastic_path_payments_stripe]

The name of the payment gateway facilitating the secure transmission of payment data.

customer_id string

Possible values: >= 3 characters and <= 1024 characters

The unique identifier for a customer.

card_id string

Possible values: >= 3 characters and <= 1024 characters

The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the card_id and customer_id attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See Card declines.

PaymentAuthorityAuthorizeNet

type stringrequired

Possible values: [authorize_net]

The name of the payment gateway facilitating the secure transmission of payment data.

payment_profile_id string

Possible values: >= 3 characters and <= 1024 characters

The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.

customer_profile_id string

Possible values: >= 3 characters and <= 1024 characters

The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.

go_live_after stringnullable

The date and time a pending subscription goes live and becomes active. See Creating a pending subscription.

Responses

200

Success. The subscription is updated.

application/json

Schema

Schema

data Subscription

id UUID (string)

The unique identifier.

type SubscriptionType (string)required

Possible values: [subscription]

attributes SubscriptionAttributesrequired

external_ref ExternalRef (string)

Possible values: <= 2048 characters

A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

account_id UUID (string)required

The unique identifier.

address_id UUID (string)

The unique identifier.

offering Offeringrequired

id UUID (string)

The unique identifier.

type SubscriptionOfferingType (string)required

Possible values: [subscription_offering]

attributes OfferingAttributesrequired

external_ref ExternalRef (string)

Possible values: <= 2048 characters

A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

name stringrequired

Possible values: >= 3 characters and <= 1024 characters

The name of the offering.

description string

Possible values: <= 1024 characters

The offering description to display to customers.

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

relationships Relationships

Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

anyOf

title

meta OfferingMetarequired

external_product_refs string[]required

owner stringrequired

The owner of a resource, either store or organization.

timestamps Timestampsrequired

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

plan_id UUID (string)required

The unique identifier.

currency CurrencyIdentifier (string)required

Possible values: <= 1024 characters

The three-letter ISO currency code in uppercase.

payment_authority object

oneOf

PaymentAuthorityStripe

type stringrequired

Possible values: [elastic_path_payments_stripe]

The name of the payment gateway facilitating the secure transmission of payment data.

customer_id string

Possible values: >= 3 characters and <= 1024 characters

The unique identifier for a customer.

card_id string

Possible values: >= 3 characters and <= 1024 characters

The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the card_id and customer_id attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See Card declines.

PaymentAuthorityAuthorizeNet

type stringrequired

Possible values: [authorize_net]

The name of the payment gateway facilitating the secure transmission of payment data.

payment_profile_id string

Possible values: >= 3 characters and <= 1024 characters

The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.

customer_profile_id string

Possible values: >= 3 characters and <= 1024 characters

The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.

relationships Relationships

Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

anyOf

title

meta SubscriptionMetarequired

owner stringrequired

The owner of a resource, either store or organization.

timestamps Timestampsrequired

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

canceled_at string

The date and time a subscription was cancelled.

paused_at string

The date and time a subscription was paused.

resumed_at string

The date and time a subscription was resumed.

end_date string

The date and time a subscription will end.

go_live_after string

The date and time a subscription will go live and become active.

go_live string

The date and time a subscription was released from the pending state and made active.

status Status (string)required

Possible values: [active, inactive]

The status of a subscription, either active or inactive.

state SubscriptionState

id UUID (string)

The unique identifier.

type SubscriptionStateType (string)required

Possible values: [subscription_state]

This represents the type of resource object being returned. Always subscription_state.

attributes SubscriptionStateAttributesrequired

action SubscriptionStateAction (string)required

Possible values: [cancel, pause, resume, pending]

The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a product.

A subscription can have the following states; canceled, paused, or resumed.

See Managing the subscription lifecycle.

meta StateMetarequired

created_at stringrequired

The date and time a resource was created.

manual_payments ManualPayments (boolean)required

When configured to true, no payment gateway is used and a pending payment is created. See External Payments.

canceled booleanrequired

Whether a subscription is canceled or not.

paused booleanrequired

Whether a subscription is paused or not.

closed booleanrequired

Whether a subscription is closed or not.

suspended booleanrequired

Whether a subscription is suspended or not.

pending booleanrequired

Whether a subscription is pending activation or not.

invoice_after stringrequired

The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.

Example (from schema)

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "subscription",
    "attributes": {
      "external_ref": "abc123",
      "account_id": "00000000-0000-0000-0000-000000000000",
      "address_id": "00000000-0000-0000-0000-000000000000",
      "offering": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "subscription_offering",
        "attributes": {
          "external_ref": "abc123",
          "name": "Magazine",
          "description": "A lovely magazine that is published every month.",
          "updated_at": "2017-01-10T11:41:19.244842Z",
          "created_at": "2017-01-10T11:41:19.244842Z"
        },
        "relationships": {
          "plans": {
            "links": {
              "related": "/offerings/:offering-id/plans",
              "self": "/offerings/:offering-id"
            },
            "data": {
              "type": "offering-plan",
              "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
            }
          }
        },
        "meta": {
          "external_product_refs": [
            "97dddc65-eabd-45d8-b45b-2ece5cfc8c50"
          ],
          "owner": "store",
          "timestamps": {
            "updated_at": "2017-01-10T11:41:19.244842Z",
            "created_at": "2017-01-10T11:41:19.244842Z"
          }
        }
      },
      "plan_id": "00000000-0000-0000-0000-000000000000",
      "currency": "USD",
      "payment_authority": {}
    },
    "relationships": {
      "plans": {
        "links": {
          "related": "/offerings/:offering-id/plans",
          "self": "/offerings/:offering-id"
        },
        "data": {
          "type": "offering-plan",
          "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
        }
      }
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "updated_at": "2017-01-10T11:41:19.244842Z",
        "created_at": "2017-01-10T11:41:19.244842Z",
        "canceled_at": "2017-01-10T11:41:19.244842Z",
        "paused_at": "2017-01-10T11:41:19.244842Z",
        "resumed_at": "2017-01-10T11:41:19.244842Z",
        "end_date": "2017-01-10T11:41:19.244842Z",
        "go_live_after": "2017-01-10T11:41:19.244842Z",
        "go_live": "2017-01-10T11:41:19.244842Z"
      },
      "status": "active",
      "state": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "subscription_state",
        "attributes": {
          "action": "cancel"
        },
        "meta": {
          "created_at": "2017-01-10T11:41:19.244842Z"
        }
      },
      "manual_payments": false,
      "canceled": true,
      "paused": true,
      "closed": true,
      "suspended": false,
      "pending": false,
      "invoice_after": "2017-01-10T11:41:19.244842Z"
    }
  }
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

missing-name

{
  "errors": [
    {
      "title": "Validation Error",
      "status": "400",
      "detail": "data.attributes.name: \"name\" is required"
    }
  ]
}

403

Forbidden. The operation is forbidden on this entity.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

not-found

{
  "errors": [
    {
      "title": "Permission denied",
      "status": "404",
      "detail": "Permission denied: plan tenancy mismatch"
    }
  ]
}

404

Not found. The requested entity does not exist.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

not-found

{
  "errors": [
    {
      "title": "Not Found",
      "status": "404",
      "detail": "No plan found"
    }
  ]
}

500

Internal server error. There was a system failure in the platform.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

internal-server-error

{
  "errors": [
    {
      "title": "Internal Server Error",
      "status": "500"
    }
  ]
}

Loading...