In this topic:

Account-Level Discounts

This example shows you how to use the Gotransverse Billing API along with the CPQ microservice to create and use discounts at the billing account level.

Example Updated: February 2018

Terminology

Account-level discount: Account-level discounts are percentage or flat amount discounts that are configured using the CPQ (Configure Price Quote) microservice and managed through the Billing microservice. For the purposes of this example, they are also called CPQ discounts. When you create an account-level discount for a billing account, the discount applies to all orders and order items placed within that billing account. An account-level discount functions like an add-on product. It is visible to the user during the order configuration process before the order is placed. Account-level discounts do not require discount codes, but they can be combined with product discounts. If used in combination, an account-level discount is calculated on the standard product price minus the product discount. Account-level discounts can be used with both subscription products and add-ons.

Product discount: Product discounts are percentage or flat amount discounts that are configured for and applied to products in Gotransverse. Product discounts require the configuration and use of a discount code that is applied during the order process. Product discounts can be combined with account-level discounts.

Prerequisites for Using Account-Level Discounts

Before using account-level discounts, you must do the following:

  • Set up a CPQ Essentials gateway.
    1. In the Gotransverse user interface navigation bar, navigate to Admin>>Integration.
    2. In the CPQ Gateway Processors pane, click Add.
    3. In the Add CPQ Gateway window that opens, enter information provided by the Gotransverse Implementation team.
      configure CPQ gateway
  • Set up an add-on product or products that will function along with the CPQ discount on a billing account to enact the account-level discounting. The add-on product is associated with all products to which the CPQ discount can be applied. The Gotransverse Implementation team will set these products up for you.

Using API Requests to Manage Account-Level Discounts

In this example, we will do the following:

  • Create a CPQ discount of 10%
  • Update the CPQ discount to 15%
  • Query the CPQ discount
  • Query for a billing account and its associated CPQ discount
  • Create an order with an account-level CPQ discount
  • Delete the CPQ discount

Example HTTP requests use path parameters. When testing this example, substitute an actual billing account ID or CPQ discount ID for {id} or {cpq_discount_id}.

Creating an Account-Level Discount

Use this request to create an account-level CPQ discount of 10%.

Request
POST https://example-tract-api.com/billing/2/billing-accounts/{id}/cpq-discounts

Body

  {
    "start_date": "2017-11-06T12:00:40.840Z", 
    "recurrance": "NONE",
    "value": 10, 
    "application_type": "PERCENTAGE",
    "price_type": "ALL"
  }

Response

  {
    "id": "4294d7d3-a23c-49a8-8d63-099520854c84", 
    "value": 10, 
	"start_date": "2017-11-06T06:00:40-06:00",			
    "application_type": "PERCENTAGE",
    "price_type": "ALL"
    "recurrance": "NONE",
  }

Updating an Account-Level Discount

Use this request to update an existing account-level cpq discount to 15%.

Request
PUT https://example-tract-api.com/billing/2/billing-accounts/{id}/cpq-discounts/{cpq_discount_id}

Body

  {
    "start_date": "2017-11-06T12:00:40.840Z", 
    "recurrance": "NONE",
    "value": 15, 
    "application_type": "PERCENTAGE",
    "price_type": "RECURRING"
  }

Response

  {
    "id": "4294d7d3-a23c-49a8-8d63-099520854c84", 
    "value": 15, 
    "start_date": "2017-11-06T06:00:40-06:00",			
    "application_type": "PERCENTAGE",
    "price_type": "RECURRING"
    "recurrance": "NONE",
  }

Querying for a CPQ Discount on a Billing Account

Use the following request to retrieve a specific CPQ discount on a specified billing account.

Request
GET https://example-tract-api.com/billing/2/billing-accounts/{id}/cpq-discounts

Response

  {
    "id": "4294d7d3-a23c-49a8-8d63-099520854c84", 
    "value": 15, 
    "start_date": "2017-11-06T06:00:40-06:00",			
    "application_type": "PERCENTAGE",
    "price_type": "RECURRING"
    "recurrance": "NONE",
  }

Querying for a Billing Account with a CPQ Discount

Use the following request to retrieve a specific billing account. The expand parameter is set to cpq_discounts in order to view CPQ discounts in the response.

Request
GET https://example-tract-api.com/billing/2/billing-accounts/{id}?expand=cpq_discounts

Response

    {
      "id": "2272769",
      "account_num": "ME1272",
      "external_account_num": null,
      "bill_type": "NONE",
      "bill_cycle": {
        "bill_cycle_type": "monthly",
        "id": "27261",
        "status": "ACTIVE",
        "name": "CPQ 4",
        "start_date": "2018-02-01T00:00:00-06:00",
        "end_date": "2018-03-01T00:00:00-06:00",
        "auto_bill": false,
        "currency_code": "USD",
        "day_of_month": 1
      },
      "responsible_party": {
        "party_type": "organization",
        "id": "2459841",
        "addresses": [
          {
          "address_type": "postal",
          "id": "6257052",
          "purpose": "BILLING",
          "country": "USA",
          "city": "Austin",
          "line1": "620 Congress Avenue",
          "region_or_state": "TX",
          "postal_code": "78701"
          }
        ],
      "organization_name": "CPQ Example",
      "tax_id_validated": false
    },
    "recurring_payments": [],
    "billing_account_category": {
      "id": "3390",
      "status": "ACTIVE",
      "name": "Default billing account category",
      "auto_pay_offset": 0
    },
    "auto_payment_authorized": false,
    "status": "ACTIVE",
    "pending_charges_total": 0,
    "balance": 0,
    "start_date": "2018-02-07T07:20:17-06:00",
    "custom_field_values": [],
    "contacts": [],
    "payment_term": {
      "id": "5204",
      "name": "Immediate",
      "term_days": 0,
      "grace_days": 0
    },
    "tax_exempt": false,
    "currency_code": "USD",
    "next_invoice_date": "2016-10-01T00:00:00-05:00",
    "responsible_account": {
      "id": "2272769",
      "account_num": "ME1272",
      "external_account_num": null
    },
    "cpq_discounts": [
      {
        "id": "6902e70a-fccb-449a-ac2b-8c5c006c71a3",
        "value": 15,
        "start_date": "2017-11-06T06:00:40-06:00",
        "application_type": "PERCENTAGE",
        "price_type": "ALL",
        "recurrence": "NONE"
      }
     ]
    }

Creating an Order for a Billing Account with a CPQ Discount

Use the following request and body to create an order on a billing account that has a CPQ discount associated with it.

Request
POST https://example-tract-api.com/billing/2/billing-accounts/{id}/orders

Body

 {
    "initial_status": "DRAFT",
    "note": "Order Note",
    "email_receipt": "true",
    "purchase_order_number": " ",
    "referral": "Clone opp test ltd",
    "order_items": [
      {
        "order_item_type": "product",
        "id": "6507729",
        "quantity": 1,
        "sequence": 1,
        "product": {
          "id": "106924",
          "name": "Sub cpq",
          "sku": "sub"
         }
      }]
  }

Response

  {
    "order_type": "sales",
    "id": "4049411",
    "note": "Order Note",
    "referral": "Clone opp test ltd",
    "order_num": "233399686",
    "order_items": [
      {
      "order_item_type": "product",
      "id": "6515874",
      "quantity": 1,
      "sequence": 1,
      "product": {
        "id": "106924",
        "name": "Sub cpq",
        "sku": "sub"
      },
      "order_items": [
        {
          "order_item_type": "add-on",
          "id": "6515875",
          "quantity": 1,
          "sequence": 2,
          "product": {
            "id": "106926",
            "name": "Discount for Default charge category",
            "sku": "sku1"
          },
          "order_items": [],
          "status": "DRAFT",
          "extended_price": -53.25,
          "awaiting_approval": false,
          "price_list": {
            "id": "2943",
            "name": "Default Price List"
          },
          "service_resources": [],
          "requested_effective_date": "2018-02-07T07:37:16-06:00",
          "operation_run_attributes": [],
          "custom_field_values": [],
          "addresses": [],
          "consume_prepaid_balance": false,
          "order_item_prices": [
            {
              "base_price_type": "one-time",
              "id": "5739334",
              "tapered": false,
              "currency_code": "USD",
              "category": {
                "charge_category_type": "price",
                "id": "29864",
                "name": "Default"
              },
              "price_override": true,
              "amount": 250,
              "taxable_amount": 0,
              "product_price": {
                "price_type": "one-time",
                "id": "255200"
              },
              "order_item_price_ranges": [
                {
                  "price_range_type": "order-item",
                  "id": "285581",
                  "price": -8.25,
                  "level": 1,
                  "quantity_begin_range": 0,
                  "currency_code": "USD"
                }
              ],
              "scheduled_charges": []
            },
            {
              "base_price_type": "recurring",
              "id": "5739335",
              "tapered": false,
              "currency_code": "USD",
              "category": {
                "charge_category_type": "price",
                "id": "29864",
                "name": "Default"
              },
              "price_override": true,
              "amount": -45,
              "taxable_amount": -45,
              "product_price": {
                "price_type": "recurring",
                "id": "255199"
              },
              "order_item_price_ranges": [
                {
                  "price_range_type": "order-item",
                  "id": "285582",
                  "price": -45,
                  "level": 1,
                  "quantity_begin_range": 0,
                  "currency_code": "USD"
                }
              ],
              "prorated_on_order": false,
              "prorated_on_cancel": false,
              "prorated_on_order_no_charge": false
              }
            ]
          }
        ],
        "status": "DRAFT",
        "extended_price": 355,
        "awaiting_approval": false,
        "price_list": {
          "id": "2943",
          "name": "Default Price List"
        },
        "service_resources": [],
        "requested_effective_date": "2018-02-07T07:37:16-06:00",
        "operation_run_attributes": [],
        "custom_field_values": [],
        "addresses": [],
        "consume_prepaid_balance": false,
        "order_item_prices": [
          {
            "base_price_type": "one-time",
            "id": "5739332",
            "tapered": false,
            "currency_code": "USD",
            "category": {
              "charge_category_type": "price",
              "id": "29864",
              "name": "Default"
            },
            "price_override": true,
            "amount": 55,
            "taxable_amount": 0,
            "product_price": {
              "price_type": "one-time",
              "id": "255198"
            },
            "order_item_price_ranges": [
              {
                "price_range_type": "order-item",
                "id": "285579",
                "price": 55,
                "level": 1,
                "quantity_begin_range": 0,
                "currency_code": "USD"
              }
            ],
            "scheduled_charges": []
          },
          {
            "base_price_type": "recurring",
            "id": "5739333",
            "tapered": false,
            "currency_code": "USD",
            "category": {
              "charge_category_type": "price",
              "id": "29864",
              "name": "Default"
            },
            "price_override": true,
            "amount": 300,
            "taxable_amount": 0,
            "product_price": {
              "price_type": "recurring",
              "id": "255195"
            },
            "order_item_price_ranges": [
              {
                "price_range_type": "order-item",
                "id": "285580",
                "price": 300,
                "level": 1,
                "quantity_begin_range": 0,
                "currency_code": "USD"
              }
            ],
            "prorated_on_order": false,
            "prorated_on_cancel": false,
            "prorated_on_order_no_charge": false
          }
        ]
      }
    ],
    "billing_account": {
      "id": "2272769",
      "account_num": "ME1272",
      "external_account_num": null,
      "bill_cycle": {
        "bill_cycle_type": "monthly",
        "id": "27261",
        "name": "CPQ 4"
      },
      "responsible_party": {
        "party_type": "organization",
        "id": "2459841"
      },
      "billing_account_category": {
        "id": "3390",
        "name": "All Accounts"
      },
      "payment_term": {
        "id": "5204",
        "name": "Immediate"
      },
      "responsible_account": {
        "id": "2272769",
        "account_num": "ME1272",
        "external_account_num": null
      }
    },
    "purchase_order_number": " ",
    "email_receipt": true,
    "order_date": "2018-02-07T07:37:16-06:00",
    "total_amount": 301.75,
    "custom_field_values": [],
    "status": "DRAFT",
    "sub_total": 301.75,
    "tax_total": 0,
    "due_now_total": 0,
    "due_now_tax_total": 0
  }

Deleting an Existing CPQ Discount from a Billing Account

Use the following request to remove a CPQ discount from a billing account.

Request
DELETE https://example-tract-api.com/billing/2/billing-accounts/{id}/cpq-discounts/{cpq_discount_id}

Response

Empty - 204 No Response
Top