Skip to content

Latest commit

 

History

History
197 lines (181 loc) · 4.17 KB

subscription.md

File metadata and controls

197 lines (181 loc) · 4.17 KB
Raw

Subscription

A subscription object is always tied to a Customer. The subscription token is only unique within the customer scope. For this reason, when you are handling individual subscriptions, you are always required to use the Customer resource.

The subscription object

Attributes

Name Type Description
object string Is "subscription"
token string The token is under the scope of a customer.
serial_number integer The sequential number for the subscription within the scope of the Space.
created integer
items object A list of invoice items for the subscription.
items->data array The list of invoice items.
items->count integer Number of invoice items.
total integer The fractional amount paid.
currency integer The currency paid in.
customer object

Example

{
	"object": "subscription",
	"token": "SUBSCRIPTION_TOKEN",
	"serial_number": 1,
	"created": 1410196578,
	"status": "active",
	"items": {
		"data": [
			{
				"object": "subscription_item",
				"item_id": "100100",
				"description": "Product 7",
				"quantity": 1,
				"discount": 0,
				"unit_amount": 1200,
				"total_amount": 1200
			},
			{
				"object": "subscription_item",
				"item_id": 101,
				"description": "Domestic shipping",
				"quantity": 1,
				"discount": 0,
				"unit_amount": 1000,
				"total_amount": 1000
			}
		],
		"count": 2
	},
	"total": 2200,
	"currency": "USD",
	"customer": {
		"object": "customer",
		"id": "CUSTOMER_TOKEN",
		"name": "John Doe",
		"email": "[email protected]",
		"created": 1410196576,
		"space": {
			"object": "space",
			"id": 1,
			"created": 1410196557,
			"url": "https://spaces.pe/s/EXAMPLE"
		}
	}
}

Retrieve a subscription

To retrieve a specific subscription resource, you need to use the Customer resource for the subscription in the URI.

Example request

$ curl https://spaces.com/api/v1/customers/CUSTOMER_TOKEN/subscriptions/SUBSCRIPTION_TOKEN \
	-u ACCESS_TOKEN:

Example response

{
	"object": "subscription",
	"token": "SUBSCRIPTION_TOKEN",
	"serial_number": 1,
	"created": 1410196578,
	"status": "active",
	"items": {
		"data": [
			{
				"object": "subscription_item",
				"item_id": "100100",
				"description": "Product 7",
				"quantity": 1,
				"discount": 0,
				"unit_amount": 1200,
				"total_amount": 1200
			},
			{
				"object": "subscription_item",
				"item_id": 101,
				"description": "Domestic shipping",
				"quantity": 1,
				"discount": 0,
				"unit_amount": 1000,
				"total_amount": 1000
			}
		],
		"count": 2
	},
	"total": 2200,
	"currency": "USD",
	"customer": {
		"object": "customer",
		"id": "CUSTOMER_TOKEN",
		"name": "John Doe",
		"email": "[email protected]",
		"created": 1410196576,
		"space": {
			"object": "space",
			"id": 1,
			"created": 1410196557,
			"url": "https://spaces.pe/s/EXAMPLE"
		}
	}
}

List all subscriptions

Returns a list of all subscriptions.

Example request

$ curl https://spaces.com/api/v1/subscriptions \
	-u ACCESS_TOKEN:

Example response

{
	"object": "list",
	"count": 2,
	"data": [
		{
			"object": "subscription",
			"token": "SUBSCRIPTION_TOKEN",
			"serial_number": 1,
			"created": 1410196578,
			"status": "active",
			"items": {
				"data": [
					{
						"object": "subscription_item",
						"item_id": "100100",
						"description": "Product 7",
						"quantity": 1,
						"discount": 0,
						"unit_amount": 1200,
						"total_amount": 1200
					},
					{
						"object": "subscription_item",
						"item_id": 101,
						"description": "Domestic shipping",
						"quantity": 1,
						"discount": 0,
						"unit_amount": 1000,
						"total_amount": 1000
					}
				],
				"count": 2
			},
			"total": 2200,
			"currency": "USD",
			"customer": {
				"object": "customer",
				"id": "CUSTOMER_TOKEN",
				"name": "John Doe",
				"email": "[email protected]",
				"created": 1410196576,
				"space": {
					"object": "space",
					"id": 1,
					"created": 1410196557,
					"url": "https://spaces.pe/s/EXAMPLE"
				}
			}
		},
		{...}
	]
}