Navbar
  • Introduction
  • Authentication
  • Versioning
  • Pagination
  • Errors
  • Rate limiting
  • Webhooks
  • Charges
  • Checkouts
  • Events
  • Introduction

    The Coinbase Commerce API provides a simple and powerful REST API to integrate bitcoin, bitcoin cash, litecoin and ethereum payments into your business or application. This API reference provides information on available endpoints and how to interact with them.

    Authentication

    Example authenticated request:

    curl https://api.commerce.coinbase.com/checkouts \
         -H "X-CC-Api-Key: <Your API Key>"
    

    Most requests to the Commerce API must be authenticated with an API key. You can create an API key in your Settings page after creating a Coinbase Commerce account.

    Authenticated API requests should be made with a X-CC-Api-Key header. Your secret API key should be passed as the value.

    If authentication fails, a JSON object with an error message will be returned as a response along with HTTP status 401.

    Versioning

    Example request:

    curl https://api.commerce.coinbase.com/checkouts \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    All API calls should include an X-CC-Version header containing the API version with which you would like to make your request. API versions are of the form YYYY-MM-DD, indicating the date on which that version was released; a new version will be released for every breaking change to the API. The latest API version is 2018-03-22.

    If no version is passed, or if an unknown or invalid version is given, the latest API version will be used and a warning will be included in the response. Be sure to include a valid version with every request in order to avoid unexpected breakage. Do not pass the current date as your version header.

    Pagination

    Example request:

    curl https://api.commerce.coinbase.com/checkouts?limit=20 \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response:

    {
        "pagination": {
            "order": "desc",
            "starting_after": null,
            "ending_before": null,
            "total": 25,
            "yielded": 20,
            "limit": 20,
            "previous_uri": null,
            "next_uri": "https://api.commerce.coinbase.com/checkouts?limit=20&starting_after=fb6721f2-1622-48f0-b713-aac6c819b67a",
            "cursor_range": ["a76721f2-1611-48fb-a513-aac6c819a9d6", "fb6721f2-1622-48f0-b713-aac6c819b67a"]
        },
        "data": [
            ...
        ]
    }
    

    All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API will construct the next call into next_uri together with all the currently used pagination parameters. You know that you have paginated all the results when the response’s next_uri is empty. Default limit is set to 25 but values up to 100 are permitted.

    Arguments

    Field Description
    order optional Order of the resources in the response. desc (default), asc
    limit optional Number of results per call. Accepted values: 0 - 100. Default 25
    starting_after optional A cursor for use in pagination. starting_after is a resource ID that defines your place in the list.
    ending_before optional A cursor for use in pagination. ending_before is a resource ID that defines your place in the list.

    Errors

    Error response

    Error response 400

    {
        "error": {
            "type"  : "invalid_request",
            "message": "Required parameter missing: name"
        }
    }
    

    All error messages include a type identifier and a human readable message.

    validation_error with status code 400 is returned when the validation of the resource fails on POST or PUT requests. Response contains errors field with a list of errors.

    Warnings

    Example warning

    {
        "warnings": [
          "Missing X-CC-Version header; serving latest API version (2018-03-22)"
        ]
    }
    

    Responses can include a warnings parameter to notify the developer of best practices, implementation suggestions or deprecation warnings. While you don’t need show warnings to the user, they are usually something you need to act on.

    Rate limiting

    Rate limiting error (429)

    {
      "error": {
        "type": "rate_limit_exceeded",
        "message": "Rate limit exceeded"
      }
    }
    

    The Coinbase Commerce API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users. By default, every user is rate limited at 25 requests per minute on the charge creation endpoint and 200 requests per minute for all other endpoints. If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error.

    Webhooks

    Example of a webhook payload

    {
        "id": 1,
        "scheduled_for": "2017-01-31T20:50:02Z",
        "event": {
            "id": "24934862-d980-46cb-9402-43c81b0cdba6",
            "resource": "event",
            "type": "charge:created",
            "api_version": "2018-03-22",
            "created_at": "2017-01-31T20:49:02Z",
            "data": {
              "code": "66BEOV2A",
              "name": "The Sovereign Individual",
              "description": "Mastering the Transition to the Information Age",
              "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
              "created_at": "2017-01-31T20:49:02Z",
              "expires_at": "2017-01-31T21:49:02Z",
              "timeline": [
                {
                  "time": "2017-01-31T20:49:02Z",
                  "status": "NEW"
                }
              ],
              "metadata": {},
              "pricing_type": "no_price",
              "payments": [],
              "addresses": {
                "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
                "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
              }
            }
        }
    }
    

    Webhooks make it easier to integrate with Coinbase Commerce by allowing you to subscribe to a set of charge events. You can subscribe to the events by going to your settings page and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for. Below is the list of all available webhook events:

    Event Description
    charge:created New charge is created
    charge:confirmed Charge has been confirmed and the associated payment is completed
    charge:failed Charge failed to complete
    charge:delayed Charge received a payment after it had been expired
    charge:pending Charge has been detected but has not been confirmed yet

    Fields

    Field Type Description
    id number Delivery attempt number
    scheduled_for timestamp Delivery schedule time
    event hash Corresponding event object

    Securing webhooks

    Every Coinbase Commerce webhook request includes an X-CC-Webhook-Signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret from your settings page. Always make sure that you verify the webhook signature before acting on it inside your system.

    Charges

    To request a cryptocurrency payment, you create a charge. You can create and view charges. Since cryptocurrency payments are push payments, a charge will expire after a waiting period (payment window) if no payment has been detected. Charges are identified by a unique code.

    Charge resource

    Example of a charge resource

    {
      "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
      "resource": "charge",
      "code": "66BEOV2A",
      "name": "The Sovereign Individual",
      "description": "Mastering the Transition to the Information Age",
      "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
      "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
      "created_at": "2017-01-31T20:49:02Z",
      "expires_at": "2017-01-31T21:49:02Z",
      "confirmed_at": "2017-01-31T20:50:02Z",
      "checkout": {
        "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
      },
      "timeline": [
        {
          "time": "2017-01-31T20:49:02Z",
          "status": "NEW"
        },
        {
          "time": "2017-01-31T20:50:02Z",
          "status": "PENDING"
        },
        {
          "time": "2017-01-31T20:50:02Z",
          "status": "CONFIRMED"
        },
        {
          "time": "2017-01-31T20:50:02Z",
          "status": "UNRESOLVED",
          "context": "UNDERPAID"
        },
        {
          "time": "2017-01-31T20:50:02Z",
          "status": "RESOLVED"
        }
      ],
      "metadata": {},
      "pricing_type": "fixed_price",
      "pricing": {
        "local": { "amount": "100.00", "currency": "USD" },
        "bitcoin": { "amount": "1.00", "currency": "BTC" },
        "ethereum": { "amount": "10.00", "currency": "ETH" }
      },
      "payments": [
        {
          "network": "ethereum",
          "transaction_id": "0xe02fead885c3e4019945428ed54d094247bada2d0ac41b08fce7ce137bf29587",
          "status": "CONFIRMED",
          "value": {
            "local": { "amount": "100.0", "currency": "USD" },
            "crypto": { "amount": "10.00", "currency": "ETH" }
          },
          "block": {
              "height": 100,
              "hash": "0xe02fead885c3e4019945428ed54d094247bada2d0ac41b08fce7ce137bf29587",
              "confirmations_accumulated": 8,
              "confirmations_required": 2
          }
        }
      ],
      "addresses": {
        "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
        "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
      }
    }
    

    Fields

    Field Type Description
    id string Charge UUID
    resource string Resource name: "charge"
    code string Charge user-friendly primary key
    name string Charge name
    description string Charge description
    logo_url string Charge image URL
    hosted_url string Hosted charge URL
    created_at timestamp Charge creation time
    expires_at timestamp Charge expiration time
    confirmed_at timestamp Charge confirmation time
    checkout hash Associated checkout resource
    timeline array Array of status update objects
    metadata hash Metadata associated with the charge
    pricing_type string Pricing type: no_price or fixed_price
    pricing hash Charge price information object
    payments array Array of charge payment objects
    addresses hash Set of addresses associated with the charge

    Charge Timeline

    Every charge object has a timeline of status updates. Charge timeline is an array of objects of the following format:

    Field Type Description
    time timestamp Time of the status update
    status string One of the following statuses: NEW, PENDING, COMPLETED, EXPIRED, UNRESOLVED, RESOLVED, CANCELED
    context string, optional For charges with UNRESOLVED status, additional context is provided. Context can be one of the following: UNDERPAID, OVERPAID, DELAYED, MULTIPLE, MANUAL, OTHER

    Pricing

    If a charge has a fixed_price pricing type, then there will be a pricing object associated with it. Pricing object is composed of local price which is set by the merchant in their native fiat currency and corresponding prices in every cryptocurrency that the merchant has activated for their account

    Field Type Description
    local money Price set by the merchant in local fiat currency
    bitcoin money, optional Price in BTC
    bitcoincash money, optional Price in BCH
    ethereum money, optional Price in ETH
    litecoin money, optional Price in LTC

    Addresses

    For every active cryptocurrency for a charge addresses object will contain an address that the buyer will be expected to pay to

    Field Type Description
    bitcoin string, optional Bitcoin address
    bitcoincash string, optional Bitcoin Cash address
    ethereum string, optional Ethereum address
    litecoin string, optional Litecoin address

    List charges

    Example request

    curl https://api.commerce.coinbase.com/charges \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
      "pagination": {
        ...
      },
      "data": [{
         "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
         "resource": "charge",
        "code": "66BEOV2A",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
        "created_at": "2017-01-31T20:49:02Z",
        "expires_at": "2017-01-31T21:49:02Z",
        "checkout": {
          "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
        },
        "timeline": [
          {
            "time": "2017-01-31T20:49:02Z",
            "status": "NEW"
          }
        ],
        "metadata": {},
        "pricing_type": "fixed_price",
        "pricing": {
          "local": { "amount": "100.00", "currency": "USD" },
          "bitcoin": { "amount": "1.00", "currency": "BTC" },
          "ethereum": { "amount": "10.00", "currency": "ETH" }
        },
        "payments": [],
        "addresses": {
          "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
          "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
        }
      }]
    }
    

    Lists all the charges

    HTTP Request

    GET https://api.commerce.coinbase.com/charges

    Show a charge

    Example request

    curl https://api.commerce.coinbase.com/charges/66BEOV2A \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
      "data": {
        "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
        "resource": "charge",
        "code": "66BEOV2A",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
        "created_at": "2017-01-31T20:49:02Z",
        "expires_at": "2017-01-31T21:49:02Z",
        "checkout": {
          "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
        },
        "timeline": [
          {
            "time": "2017-01-31T20:49:02Z",
            "status": "NEW"
          }
        ],
        "metadata": {},
        "pricing_type": "fixed_price",
        "pricing": {
          "local": { "amount": "100.00", "currency": "USD" },
          "bitcoin": { "amount": "1.00", "currency": "BTC" },
          "ethereum": { "amount": "10.00", "currency": "ETH" }
        },
        "payments": [],
        "addresses": {
          "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
          "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
        }
      }
    }
    

    Retrieves the details of a charge that has been previously created. Supply the unique charge code that was returned when the charge was created. This information is also returned when a charge is first created.

    HTTP Request

    GET https://api.commerce.coinbase.com/charges/:charge_code|:charge_id

    Create a charge

    Example request

    curl https://api.commerce.coinbase.com/charges \
         -X POST \
         -H 'Content-Type: application/json' \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
         -d '{
           "name": "The Sovereign Individual",
           "description": "Mastering the Transition to the Information Age",
           "local_price": {
             "amount": "100.00",
             "currency": "USD"
           },
           "pricing_type": "fixed_price",
           "metadata": {
             "customer_id": "id_1005",
             "customer_name": "Satoshi Nakamoto"
           },
           "redirect_url": "https://charge/completed/page",
           "cancel_url": "https://charge/canceled/page",
         }'
    

    Response (201)

    {
      "data": {
         "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
         "resource": "charge",
        "code": "66BEOV2A",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
        "created_at": "2017-01-31T20:49:02Z",
        "expires_at": "2017-01-31T21:49:02Z",
        "timeline": [
          {
            "time": "2017-01-31T20:49:02Z",
            "status": "NEW"
          }
        ],
        "metadata": {
          "customer_id": "id_1005",
          "customer_name": "Satoshi Nakamoto"
        },
        "pricing_type": "fixed_price",
        "pricing": {
          "local": { "amount": "100.00", "currency": "USD" },
          "bitcoin": { "amount": "1.00", "currency": "BTC" },
          "ethereum": { "amount": "10.00", "currency": "ETH" }
        },
        "payments": [],
        "addresses": {
          "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
          "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
        },
        "redirect_url": "https://charge/completed/page",
        "cancel_url": "https://charge/canceled/page",
      }
    }
    

    To get paid in cryptocurrency, you need to create a charge object and provide the user with a cryptocurrency address to which they must send cryptocurrency. Once a charge is created a customer must broadcast a payment to the blockchain before the charge expires.

    HTTP Request

    POST https://api.commerce.coinbase.com/charges

    Arguments

    Parameter Type Required Description
    name string Required Charge name, 100 characters or less
    description string Required More detailed description of the charge, 200 characters or less
    pricing_type string Required Charge pricing type: no_price or fixed_price
    local_price money Optional Price in local fiat currency
    metadata hash Optional Developer defined key value pairs
    redirect_url string Optional Redirect URL
    cancel_url string Optional Cancel URL

    Cancel a charge

    Example request

    curl https://api.commerce.coinbase.com/charges/66BEOV2A/cancel \
         -X POST \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
      "data": {
        "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
        "resource": "charge",
        "code": "66BEOV2A",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
        "created_at": "2017-01-31T20:49:02Z",
        "expires_at": "2017-01-31T21:49:02Z",
        "checkout": {
          "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
        },
        "timeline": [
          {
            "time": "2017-01-31T20:49:02Z",
            "status": "NEW"
          }
        ],
        "metadata": {},
        "pricing_type": "fixed_price",
        "pricing": {
          "local": { "amount": "100.00", "currency": "USD" },
          "bitcoin": { "amount": "1.00", "currency": "BTC" },
          "ethereum": { "amount": "10.00", "currency": "ETH" }
        },
        "payments": [],
        "addresses": {
          "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
          "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
        },
        "redirect_url": "https://charge/completed/page",
        "cancel_url": "https://charge/canceled/page",
      }
    }
    

    Cancels a charge that has been previously created. Supply the unique charge code that was returned when the charge was created.

    Note: Only new charges can be successfully canceled. Once payment is detected, charge can no longer be canceled.

    HTTP Request

    POST https://api.commerce.coinbase.com/charges/:charge_code|:charge_id

    Resolve a charge

    Example request

    curl https://api.commerce.coinbase.com/charges/66BEOV2A/resolve \
         -X POST \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
      "data": {
        "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
        "resource": "charge",
        "code": "66BEOV2A",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
        "created_at": "2017-01-31T20:49:02Z",
        "expires_at": "2017-01-31T21:49:02Z",
        "checkout": {
          "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
        },
        "timeline": [
          {
            "time": "2017-01-31T20:49:02Z",
            "status": "NEW"
          }
        ],
        "metadata": {},
        "pricing_type": "fixed_price",
        "pricing": {
          "local": { "amount": "100.00", "currency": "USD" },
          "bitcoin": { "amount": "1.00", "currency": "BTC" },
          "ethereum": { "amount": "10.00", "currency": "ETH" }
        },
        "payments": [],
        "addresses": {
          "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
          "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
        },
        "redirect_url": "https://charge/completed/page",
        "cancel_url": "https://charge/canceled/page",
      }
    }
    

    Resolve a charge that has been previously marked as unresolved. Supply the unique charge code that was returned when the charge was created.

    Note: Only unresolved charges can be successfully resolved. For more on unresolved charges, check out at Charge timeline

    HTTP Request

    POST https://api.commerce.coinbase.com/charges/:charge_code|:charge_id

    Checkouts

    Checkouts make it possible to sell a single fixed price item or accept arbitrary amounts of cryptocurrency very easily. Checkouts can have many charges and each charge is automatically generated on a per customer basis. Checkouts can also be quickly integrated into a website by embedding payment buttons. Each checkout has a publicly accessible hosted page that can be shared with anyone.

    Checkout resource

    Example of a checkout resource

    {
        "id": "30934862-d980-46cb-9402-43c81b0cabd5",
        "resource": "checkout",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
        "requested_info": [ "name", "email" ],
        "pricing_type": "fixed_price",
        "local_price": { "amount": "100.0", "currency": "USD" }
    }
    

    Fields

    Field Type Description
    id string Checkout UUID
    resource string Resource name: "checkout"
    name string Checkout name
    description string Checkout description
    logo_url string, optional Checkout image URL
    requested_info array, optional Array of strings specifying what information the merchants wants to collect from the buyers: name, email
    pricing_type string Pricing type: no_price or fixed_price
    local_price money, optional If pricing_type is fixed_price, then this field will specify the price

    List checkouts

    Example request

    curl https://api.commerce.coinbase.com/checkouts \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
        "pagination": {
            ...
        },
        "data": [{
            "id": "30934862-d980-46cb-9402-43c81b0cabd5",
            "resource": "checkout",
            "name": "The Sovereign Individual",
            "description": "Mastering the Transition to the Information Age",
            "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
            "requested_info": [ ],
            "pricing_type": "no_price",
        }]
    }
    

    Lists all the checkouts

    HTTP Request

    GET https://api.commerce.coinbase.com/checkouts

    Show a checkout

    Example request

    curl https://api.commerce.coinbase.com/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
        "data": {
            "id": "30934862-d980-46cb-9402-43c81b0cabd5",
            "resource": "checkout",
            "name": "The Sovereign Individual",
            "description": "Mastering the Transition to the Information Age",
            "logo_url": "https://commerce.coinbase.com/charges/ybjknds.png",
            "requested_info": [ ],
            "pricing_type": "no_price",
        }
    }
    

    Show a single checkout

    HTTP Request

    GET https://api.commerce.coinbase.com/checkouts/:checkout_id

    Create a checkout

    Example request

    curl https://api.commerce.coinbase.com/checkouts \
         -X POST \
         -H 'Content-Type: application/json' \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
         -d '{
             "name": "The Sovereign Individual",
             "description": "Mastering the Transition to the Information Age",
             "local_price": {
                 "amount": "100.00",
                 "currency": "USD"
             },
           "pricing_type": "fixed_price",
             "requested_info": ["email"]
         }'
    

    Response (201)

    {
        "data": {
            "id": "30934862-d980-46cb-9402-43c81b0cabd5",
            "resource": "checkout",
            "name": "The Sovereign Individual",
            "description": "Mastering the Transition to the Information Age",
            "requested_info": ["email"],
            "pricing_type": "fixed_price",
            "local_price": {"amount": "100.00", "currency": "USD"}
        }
    }
    

    Create a new checkout.

    HTTP Request

    POST https://api.commerce.coinbase.com/checkouts

    Arguments

    Parameter Type Required Description
    name string Required Checkout name, 100 characters or less
    description string Required More detailed description, 200 characters or less
    pricing_type string Required Checkout pricing type: no_price or fixed_price
    local_price money Optional Price in local fiat currency
    requested_info array Optional Information to collect from the customer: email, name

    Update a checkout

    Example request

    curl https://api.commerce.coinbase.com/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
         -X PUT \
         -H 'Content-Type: application/json' \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
         -d '{
             "local_price": {
                 "amount": "200.00",
                 "currency": "USD"
             }
         }'
    

    Response (200)

    {
        "data": {
            "id": "30934862-d980-46cb-9402-43c81b0cabd5",
            "resource": "checkout",
            "name": "The Sovereign Individual",
            "name": "The Sovereign Individual",
            "description": "Mastering the Transition to the Information Age",
            "requested_info": ["email"],
            "pricing_type": "fixed_price",
            "local_price": {"amount": "200.00", "currency": "USD"}
        }
    }
    

    Update a checkout.

    HTTP Request

    PUT https://api.commerce.coinbase.com/checkouts/:checkout_id

    Arguments

    Parameter Type Required Description
    name string Required Checkout name
    description string Required More detailed description
    local_price money Optional Price in local fiat currency
    requested_info array Optional Information to collect from the customer: email, name

    Delete a checkout

    Example request

    curl https://api.commerce.coinbase.com/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
         -X DELETE \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Response (200)

    Delete a checkout.

    HTTP Request

    DELETE https://api.commerce.coinbase.com/checkouts/:checkout_id

    Events

    Events let you know when a charge is updated. When an event occurs we create a new event object. Retrieve individual events or a list of events. You can also subscribe to webhook notifications which send event objects directly to an endpoint on your server. Learn more about webhooks.

    Event resource

    Example of an event resource

    {
        "id": "24934862-d980-46cb-9402-43c81b0cdba6",
        "resource": "event",
        "type": "charge:created",
        "api_version": "2018-03-22",
        "created_at": "2017-01-31T20:49:02Z",
        "data": {
          "code": "66BEOV2A",
          "name": "The Sovereign Individual",
          "description": "Mastering the Transition to the Information Age",
          "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
          "created_at": "2017-01-31T20:49:02Z",
          "expires_at": "2017-01-31T21:49:02Z",
          "timeline": [
            {
              "time": "2017-01-31T20:49:02Z",
              "status": "NEW"
            }
          ],
          "metadata": {},
          "pricing_type": "no_price",
          "payments": [],
          "addresses": {
            "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
            "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
          }
        }
    }
    

    Fields

    Field Type Description
    id string Event UUID
    resource string Resource name: "event"
    type string Event type: charge:created, charge:confirmed, charge:failed, charge:delayed, charge:pending
    created_at timestamp Event creation time
    api_version string API version of the data payload
    data hash Event payload: resource of the associated object (e.g. charge) at the time of the event

    Types of events

    This is a list of all the types of events we currently send. You should not assume that only these types exist as we may add more events over time.

    Event Type Description
    charge:created New charge is created
    charge:confirmed Charge has been confirmed and the associated payment is completed
    charge:failed Charge failed to complete
    charge:delayed Charge received a payment after it had been expired
    charge:pending Charge has been detected but has not been confirmed yet

    List events

    Example request

    curl https://api.commerce.coinbase.com/events \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
        "pagination": {
            ...
        },
        "data": [{
            "id": "24934862-d980-46cb-9402-43c81b0cdba6",
            "resource": "event",
            "type": "charge:created",
            "api_version": "2018-03-22",
            "created_at": "2017-01-31T20:49:02Z",
            "data": {
              "code": "66BEOV2A",
              "name": "The Sovereign Individual",
              "description": "Mastering the Transition to the Information Age",
              "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
              "created_at": "2017-01-31T20:49:02Z",
              "expires_at": "2017-01-31T21:49:02Z",
              "timeline": [
                {
                  "time": "2017-01-31T20:49:02Z",
                  "status": "NEW"
                }
              ],
              "metadata": {},
              "pricing_type": "no_price",
              "payments": [],
              "addresses": {
                "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
                "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
              }
        }
        }]
    }
    

    Lists all the events

    HTTP Request

    GET https://api.commerce.coinbase.com/events

    Show an event

    Example request

    curl https://api.commerce.coinbase.com/events/24934862-d980-46cb-9402-43c81b0cdba6 \
         -H "X-CC-Api-Key: <Your API Key>" \
         -H "X-CC-Version: 2018-03-22"
    

    Example response

    {
        "data": {
            "id": "24934862-d980-46cb-9402-43c81b0cdba6",
            "resource": "event",
            "type": "charge:created",
            "api_version": "2018-03-22",
            "created_at": "2017-01-31T20:49:02Z",
            "data": {
              "code": "66BEOV2A",
              "name": "The Sovereign Individual",
              "description": "Mastering the Transition to the Information Age",
              "hosted_url": "https://commerce.coinbase.com/charges/66BEOV2A",
              "created_at": "2017-01-31T20:49:02Z",
              "expires_at": "2017-01-31T21:49:02Z",
              "timeline": [
                {
                  "time": "2017-01-31T20:49:02Z",
                  "status": "NEW"
                }
              ],
              "metadata": {},
              "pricing_type": "no_price",
              "payments": [],
              "addresses": {
                "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
                "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
              }
            }
        }
    }
    

    Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.

    HTTP Request

    GET https://api.commerce.coinbase.com/events/:event_id