In this topic:

Orders

This example shows you how to use the Gotransverse Billing API to create an order.

Example Updated: February 2018

Terminology

Order: A collection of order items that are purchased together by the customer. The processing of an order creates a service.

Service Resource Category: A grouping used to specify the type of usage intended for the service being ordered. Service resources are unique identifiers of services for usage measurement.

SKU: A stock-keeping unit identifier (SKU) associated with a product.

Creating an Order

Orders for usage-based products require more information than orders for products that aren't usage-based. See each example type below.

Order for Non-Usage Product

To create an order for an existing billing account, we need the billing account ID and SKU of the product that the customer wants to order.

Create Order

In the following example request, we are creating an order for billing account ID 2273093 for a product with an SKU value of "Example."
You can also use the product ID to create an order. To do so, first query for a product using the SKU and its value as a query parameter.

Request
POST https://example-tract-api.com/billing/2/billing-accounts/2273093/orders

Body

{
  "order_date": "2018-02-13T06:00:00.000Z",
  "order_type": "sales",
  "order_items": [
    {
      "order_item_type": "product",
      "quantity": "1",
      "product": {
        "sku": "Example"
      }
    }
  ]
}

Response

{
    "order_type": "sales",
    "id": "4058442",
    "order_num": "233512892",
    "order_items": [
        {
            "order_item_type": "product",
            "id": "6525266",
            "quantity": 1,
            "sequence": 1,
            "product": {
                "id": "108541",
                "name": "Example Product",
                "sku": "Example"
            },
            "order_items": [],
            "status": "COMPLETED",
            "extended_price": 100,
            "awaiting_approval": false,
            "price_list": {
                "id": "2906",
                "name": "Default Price List"
            },
            "service_resources": [],
            "requested_effective_date": "2018-02-13T00:00:00-06:00",
            "operation_run_attributes": [],
            "custom_field_values": [],
            "addresses": [],
            "consume_prepaid_balance": false,
            "order_item_prices": [
                {
                    "order_item_price_type": "recurring",
                    "id": "5749137",
                    "tapered": false,
                    "currency_code": "USD",
                    "category": {
                        "charge_category_type": "price",
                        "id": "29662",
                        "name": "Default"
                    },
                    "price_override": true,
                    "amount": 100,
                    "taxable_amount": 0,
                    "product_price": {
                        "product_price_type": "recurring",
                        "id": "257401"
                    },
                    "price_ranges": [
                        {
                            "price_range_type": "order-item",
                            "id": "300546",
                            "price": 100,
                            "level": 1,
                            "quantity_begin_range": 0,
                            "currency_code": "USD"
                        }
                    ],
                    "prorated_on_order": false,
                    "prorated_on_cancel": false,
                    "prorated_on_order_no_charge": false
                }
            ],
            "service": {
                "id": "4914008"
            }
        }
    ],
    "billing_account": {
        "id": "2273093",
        "account_num": "32",
        "external_account_num": "5"
    },
    "email_receipt": false,
    "order_date": "2018-02-13T00:00:00-06:00",
    "total_amount": 100,
    "custom_field_values": [],
    "status": "COMPLETED",
    "sub_total": 100,
    "tax_total": 0,
    "due_now_total": 0,
    "due_now_tax_total": 0
}

Order for Usage-Based Product

If the product is a usage-based product, we also need the service resource category ID in addition to the billing account ID and SKU to create an order.

Query for Service Resource Category

Request
GET https://example-tract-api.com/billing/2/resource-categories

Response

[
    {
        "id": "46",
        "name": "USAGE ID",
        "resource_type": "service",
        "status": "ACTIVE",
        "allow_multiple_services": false
    }
]

Create Order

In the following example request, we are creating an order for billing account ID 1382 for a product with a service resource category ID of 46 and an SKU value of "SUBSCRIPTION."
You can also use the product ID to create an order. To do so, first query for a product using the SKU and its value as a query parameter.

Request
POST https://example-tract-api.com/billing/2/billing-accounts/1382/orders

Body

{
  "order_date": "2017-09-10T06:00:00.000Z",
  "order_type": "sales",
  "order_items": [
    {
      "order_item_type": "product",
      "quantity": "1",
      "product": {
        "sku": "SUBSCRIPTION"
      },
      "service_resources": [{
            "identifier": "7e0602fc-7543-445d-afd3-d50e139883f7",
            "category": {
                "id": "46"
            },
            "resource_type": "service"
        }]
    }
  ]
}

The response contains information for the created services.

Response

{
    "order_type": "sales",
    "id": "13502",
    "order_num": "210164642",
    "order_items": [
        {
            "order_item_type": "product",
            "quantity": 1,
            "sequence": 1,
            "product": {
                "name": "Subscription",
                "sku": "SUBSCRIPTION",
                "id": "424"
            },
            "id": "14379",
            "order_items": [],
            "status": "COMPLETED",
            "extended_price": 0,
            "awaiting_approval": false,
            "price_list": {
                "id": "10",
                "name": "Default Price List"
            },
            "service_resources": [
                {
                    "resource_type": "service",
                    "category": {
                        "id": "46",
                        "name": "Usage ID"
                    },
                    "status": "ACTIVE",
                    "id": "12271",
                    "identifier": "7e0602fc-7543-445d-afd3-d50e139883f7"
                }
            ],
            "requested_effective_date": "2017-09-10T01:00:00-05:00",
            "operation_run_attributes": [],
            "custom_field_values": [],
            "addresses": [],
            "consume_prepaid_balance": false,
            "order_item_prices": [
                {
                    "order_item_price_type": "recurring",
                    "id": "14379",
                    "tapered": false,
                    "currency_code": "USD",
                    "category": {
                        "charge_category_type": "price",
                        "name": "Subscription",
                        "id": "282"
                    },
                    "price_override": true,
                    "amount": 0,
                    "taxable_amount": 0,
                    "product_price": {
                        "product_price_type": "recurring",
                        "id": "1196"
                    },
                    "price_ranges": [
                        {
                            "price_range_type": "order-item",
                            "price": 0,
                            "level": 1,
                            "id": "3216",
                            "quantity_begin_range": 0,
                            "currency_code": "USD"
                        }
                    ],
                    "prorated_on_order": false,
                    "prorated_on_cancel": false,
                    "prorated_on_order_no_charge": false,
                    "usage_rules": [
                        {
                            "usage_rule_type": "order-item",
                            "name": " Usage - Pre Rated",
                            "status": "ACTIVE",
                            "id": "8948",
                            "allowance_amount": -1,
                            "allowance_uom": "COUNT",
                            "rule_order": 1,
                            "prorated_on_order": false,
                            "prorated_on_cancel": false,
                            "roll_over_type": "NONE",
                            "allowance_type": "UNLIMITED",
                            "valid_from": "2017-01-01T00:00:00-06:00",
                            "rule_type": "TAPERED",
                            "spec": {
                                "usage_rule_specification_type": "formula",
                                "operator": "EQUALS",
                                "id": "13505",
                                "field_name": "TEXT01",
                                "field_value": "SUBSCRIPTION"
                            },
                            "usage_rate": {
                                "rate_type": "pass-through",
                                "uom": "EVENT",
                                "id": "15651",
                                "valid_from": "2017-01-01T00:00:00-06:00",
                                "charge_category": {
                                    "charge_category_type": "usage-charge",
                                    "name": "Usage",
                                    "id": "288"
                                },
                                "usage_field_name": "NUMBER01"
                            },
                            "product_usage_rule": {
                                "usage_rule_type": "product",
                                "name": "Usage - Pre Rated",
                                "id": "902"
                            }
                        }
                    ]
                }
            ],
            "service": {
                "id": "13586"
            }
        }
    ],
    "billing_account": {
        "id": "1382",
        "account_num": "2001",
        "external_account_num": "902322324"
    },
    "email_receipt": false,
    "order_date": "2017-09-10T01:00:00-05:00",
    "total_amount": 0,
    "custom_field_values": [],
    "status": "COMPLETED",
    "sub_total": 0,
    "tax_total": 0,
    "due_now_total": 0,
    "due_now_tax_total": 0
}

More Information about Orders

To learn more about orders and order status, refer to the User Guide Orders topic.

To see API reference information for orders, refer to the Order section of the Billing API reference.

Top