docs: adds first version of REST docs (#116)
This commit is contained in:
Sebastian Rindom
@@ -0,0 +1,317 @@
|
||||
title: Carts
|
||||
domain: store
|
||||
route: /carts
|
||||
description: >
|
||||
A Cart is the preliminary step to an Order. The Cart holds a collection of
|
||||
items that the customer wishes to purchase, along with the customer's
|
||||
preferred payment and shipping method.
|
||||
endpoints:
|
||||
- path: /
|
||||
method: POST
|
||||
title: Create a Cart
|
||||
body:
|
||||
- name: region_id
|
||||
type: String
|
||||
required: false
|
||||
description: Id of the region to associate the cart with.
|
||||
- name: items
|
||||
type: List
|
||||
required: false
|
||||
description: List of objects with `variantId` and `quantity`.
|
||||
description: >
|
||||
Creates a Cart within the given region and with the initial items. If no
|
||||
`region_id` is provided the cart will be associated with the first Region
|
||||
available. If no items are provided the cart will be empty after creation.
|
||||
If a user is logged in the cart's customer id and email will be set.
|
||||
- path: /:id
|
||||
method: GET
|
||||
title: Retrieve a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
description: >
|
||||
Retrieves an existing cart.
|
||||
- path: /:id
|
||||
method: POST
|
||||
title: Update a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
body:
|
||||
- name: region_id
|
||||
type: String
|
||||
description: Id of a region.
|
||||
- name: email
|
||||
type: String
|
||||
description: >
|
||||
Customer's email where they will receive transactional emails etc.
|
||||
- name: billing_address
|
||||
type: Address
|
||||
description: >
|
||||
The billing address for the order.
|
||||
- name: shipping_address
|
||||
type: Address
|
||||
description: >
|
||||
The shipping address for the order. Will be sent to the fulfillment
|
||||
provider when the items are ready to be shipped.
|
||||
- name: discounts
|
||||
type: List
|
||||
description: >
|
||||
A list of objects with `code` that represents a discount code to be
|
||||
applied to the cart.
|
||||
description: >
|
||||
Updates an existing cart with the provided data. Updating the `region_id`
|
||||
will change the prices of the items in the cart to match the prices
|
||||
defined for the region. You can apply multiple discounts at once by
|
||||
calling the endpoint with an array of discounts.
|
||||
- path: /:id/line-items
|
||||
method: POST
|
||||
title: Add a Line Item to a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
body:
|
||||
- name: variant_id
|
||||
type: String
|
||||
required: true
|
||||
description: The id of the variant that should be added to the cart.
|
||||
- name: quantity
|
||||
type: Integer
|
||||
required: true
|
||||
description: >
|
||||
The quantity of the variant to add to the cart. Must be
|
||||
greater than 0.
|
||||
- name: metadata
|
||||
type: Object
|
||||
description: >
|
||||
Optional metadata that may be needed for display purposes or other
|
||||
functionality.
|
||||
- path: /:id/line-items/:line_id
|
||||
method: POST
|
||||
title: Update a Line Item
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart to update.
|
||||
- name: line_id
|
||||
type: String
|
||||
description: Id of the line to update.
|
||||
body:
|
||||
- name: quantity
|
||||
type: Integer
|
||||
description: The desired quantity of the line item.
|
||||
description: >
|
||||
Updates the quantity of a line item. If the variant associated with the
|
||||
line item is stock managed, the endpoint will respond with an error when
|
||||
the inventory level cannot fulfill the desired quantity.
|
||||
- path: /:id/line-items/:line_id
|
||||
method: DELETE
|
||||
title: Remove a Line Item
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
- name: line_id
|
||||
type: String
|
||||
description: Id of the line item to remove.
|
||||
description: >
|
||||
Removes a the given line item from the cart.
|
||||
- path: /:id/discounts/:code
|
||||
method: DELETE
|
||||
title: Remove a Discount Code
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
- name: code
|
||||
type: String
|
||||
description: The discount code to remove
|
||||
description: Removes a discount code from the cart.
|
||||
- path: /:id/payment-sessions
|
||||
method: POST
|
||||
title: Initialize Payment Sessions for a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
description: >
|
||||
Initializes the payment sessions that can be used to pay for the items of
|
||||
the cart. This is usually called when a customer proceeds to checkout.
|
||||
- path: /:id/payment-sessions/:provider_id
|
||||
method: DELETE
|
||||
title: Delete a Payment Session
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
- name: provider_id
|
||||
type: String
|
||||
description: >
|
||||
Id of the provider that created the payment session to remove.
|
||||
description: >
|
||||
Deletes a payment session. Note that this will initialize a new payment
|
||||
session with the provider. This is usually used if the payment session
|
||||
reaches a state that cannot be recovered from.
|
||||
- path: /:id/payment-method
|
||||
method: POST
|
||||
title: Set the Payment Method for a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
body:
|
||||
- name: provider_id
|
||||
type: String
|
||||
required: true
|
||||
description: >
|
||||
Id of the provider that offers the payment method.
|
||||
- name: data
|
||||
type: Dictionary
|
||||
description: >
|
||||
Used to hold any data that the payment method may need to process the
|
||||
payment. The requirements of `data` will be different across payment
|
||||
methods, and you should look at your installed payment providers to
|
||||
find out what to send.
|
||||
description: >
|
||||
Adds or updates the payment method that will be used to pay for the items
|
||||
in the cart. The payment is not processed until the payment provider's
|
||||
authorization functionality is called. You should consult with your
|
||||
installed payment plugins to find information about how to authorize a
|
||||
payment.
|
||||
- path: /:id/shipping-methods
|
||||
method: POST
|
||||
title: Add a Shipping Method to a Cart
|
||||
params:
|
||||
- name: id
|
||||
type: String
|
||||
description: Id of the cart.
|
||||
body:
|
||||
- name: option_id
|
||||
type: String
|
||||
required: true
|
||||
description: The id of the shipping option to use.
|
||||
- name: data
|
||||
type: Dictionary
|
||||
description: >
|
||||
Used to hold any data that the shipping method may need to process the
|
||||
fulfillment of the order. Look at the documentation for your installed
|
||||
fulfillment providers to find out what to send.
|
||||
description: >
|
||||
Adds a shipping method to the cart.
|
||||
response: |
|
||||
{
|
||||
"cart": {
|
||||
"_id": "5f68a234d694d000217a4d64",
|
||||
"customer_id": "",
|
||||
"region_id": "5f4cd57a5d1e3200214c0e4e",
|
||||
"email": "",
|
||||
"shipping_address": {
|
||||
"_id": "5f68a234d694d000217a4d65",
|
||||
"country_code": "US"
|
||||
},
|
||||
"items": [
|
||||
{
|
||||
"is_giftcard": false,
|
||||
"has_shipping": false,
|
||||
"returned": false,
|
||||
"fulfilled": false,
|
||||
"fulfilled_quantity": 0,
|
||||
"returned_quantity": 0,
|
||||
"_id": "5f72f79c2834b400216b1a54",
|
||||
"title": "Line Item",
|
||||
"description": "240x260",
|
||||
"quantity": 1,
|
||||
"thumbnail": "https://example-thumbnail.com",
|
||||
"content": {
|
||||
"unit_price": 303.2,
|
||||
"variant": {
|
||||
"_id": "5f4cf81a2ac41700211f6e63",
|
||||
"barcode": "",
|
||||
"image": "",
|
||||
"published": true,
|
||||
"inventory_quantity": 11,
|
||||
"allow_backorder": false,
|
||||
"manage_inventory": true,
|
||||
"title": "1234",
|
||||
"sku": "SKU1234",
|
||||
"ean": "1111111111111",
|
||||
"options": [
|
||||
{
|
||||
"_id": "5f4cf81a2ac41700211f6e64",
|
||||
"value": "1234",
|
||||
"option_id": "5f4cf81a2ac41700211f6e62"
|
||||
}
|
||||
],
|
||||
"prices": [
|
||||
{
|
||||
"_id": "5f4cf81a2ac41700211f6e65",
|
||||
"currency_code": "SEK",
|
||||
"amount": 3180
|
||||
},
|
||||
{
|
||||
"_id": "5f4cf81a2ac41700211f6e66",
|
||||
"currency_code": "EUR",
|
||||
"amount": 303.2
|
||||
},
|
||||
{
|
||||
"_id": "5f4cf81a2ac41700211f6e67",
|
||||
"currency_code": "DKK",
|
||||
"amount": 2260
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"origin_country": "Portugal"
|
||||
}
|
||||
},
|
||||
"product": {
|
||||
"_id": "5f4cf81a2ac41700211f6e61",
|
||||
"description": "100% Organic",
|
||||
"tags": "",
|
||||
"is_giftcard": false,
|
||||
"images": [],
|
||||
"thumbnail": "https://example-thumbnail.com",
|
||||
"variants": [
|
||||
"5f4cf81a2ac41700211f6e63"
|
||||
],
|
||||
"published": false,
|
||||
"title": "Line Item",
|
||||
"options": [
|
||||
{
|
||||
"values": [],
|
||||
"_id": "5f4cf81a2ac41700211f6e62",
|
||||
"title": "Size"
|
||||
}
|
||||
]
|
||||
},
|
||||
"quantity": 1
|
||||
}
|
||||
}
|
||||
],
|
||||
"discounts": [],
|
||||
"payment_sessions": [],
|
||||
"shipping_methods": [],
|
||||
"shipping_total": 0,
|
||||
"discount_total": 0,
|
||||
"tax_total": 0,
|
||||
"subtotal": 303.2,
|
||||
"total": 303.2,
|
||||
"region": {
|
||||
"_id": "5f4cd57a5d1e3200214c0e4e",
|
||||
"tax_rate": 0,
|
||||
"countries": [
|
||||
"US"
|
||||
],
|
||||
"payment_providers": [
|
||||
"stripe"
|
||||
],
|
||||
"fulfillment_providers": [
|
||||
"shiphero"
|
||||
],
|
||||
"name": "United States",
|
||||
"currency_code": "EUR",
|
||||
"tax_code": "ABR"
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user