WatchGuard Product Order API

Version: 1.7.2

Version History

Download the API specification

Introduction

This API is reserved for WatchGuard distributors only. If you are a WatchGuard Partner or Service Provider, you cannot use this API.

The WatchGuard Product Order API is a REST API that distributors can use to order and manage subscriptions for WatchGuard products.

The Product Order API eliminates the need to exchange order data manually and enables distributors to:

• Retrieve data from the WatchGuard product catalog to use in their online portals.
• Submit purchase orders to WatchGuard when partners order products.
• Associate device serial numbers with subscription contracts (physical hardware subscriptions only).
• Cancel subscription contracts.
• Retrieve information for invoices and subscription contracts.
• Retrieve shipping information and other details for drop-ship orders.
• Retrieve license usage details for partner accounts.

This API documentation explains how to access the Product Order API and includes examples to help you get started. For detailed information about the Product Order API endpoints, see the API specification.

Key Terms

These terms describe product order and subscription billing concepts:

Partner — Company that sells WatchGuard devices, products, and services to customers. Partners are sometimes referred to as Resellers.

Distributor — Company that fulfills partner orders for WatchGuard products and helps partners to deliver network security solutions.

Product — SKU that distributors can order from the WatchGuard product catalog. For example, WatchGuard Firebox M370 with 3-yr Total Security Suite Monthly Subscription.

Service Suite — Product component that defines which subscription services are available on a device. Service suite options are Standard Support, Basic Security, and Total Security.

Serial Number — Unique number that identifies a specific WatchGuard device.

Subscription Contract — Details of a subscription purchased by a partner for a WatchGuard product. Includes order and billing information. This can be a three year contract (paid monthly for 36 months) or a one month contract.

Grace Period — The amount of time between the date WatchGuard creates a subscription contract and the date billing starts. For hardware subscriptions, partners can activate and use a device in the grace period. For software subscriptions, partners can allocate licenses in the grace period.

Feature Key — File that enables features and services on a WatchGuard device. Each feature key includes an expiration date, after which the device returns to an out-of-box state that allows only one Internet connection and one connected device.

Drop-ship — Type of order fulfillment where WatchGuard ships physical hardware devices directly to partners on behalf of a distributor.

About Subscription Billing

The WatchGuard Product Order API helps distributors to integrate their systems with the WatchGuard product catalog and submit order information to WatchGuard.

When a customer orders a subscription product from a distributor, the subscription billing process starts. The subscription billing process includes these steps:

Step 1 — Partner Orders a Product from a Distributor

The WatchGuard product catalog includes details of WatchGuard products that partners can purchase from distributors.

Each product in the product catalog represents a subscription for a specific software product or hardware device model for a specific contract term (three years or one month) and a specific service suite (Standard Support, Basic Security, or Total Security).

Distributors can include information from the WatchGuard product catalog in their online portals. Partners then use the online portal to select the WatchGuard products they want to order.

To get information from the WatchGuard product catalog, you can make calls to the Products endpoints in the Product Order API. For more information, see Query the WatchGuard Product Catalog.

Step 2 — Distributor Submits a Purchase Order to WatchGuard

After a partner orders WatchGuard products from a distributor, the distributor must submit a purchase order to WatchGuard. Purchase orders include a purchase order number, the reseller ID of the partner, and a list of the products ordered.

For software products, you must order the provisioning SKUs for the products you want:

• Purchase orders for AuthPoint products must include one of these provisioning SKUs:
  • WGATH550 — WatchGuard AuthPoint MFA Subscription Provisioning
  • WGTIS550 — WatchGuard AuthPoint Total Identity Security Subscription Provisioning
• Purchase orders for Endpoint Security software products must include one of these provisioning SKUs:
  • WGEPP39900 — WatchGuard EPP - Monthly Subscription - Provisioning
  • WGEDR39900 — WatchGuard EDR - Monthly Subscription - Provisioning
  • WGEPDR39900 — WatchGuard EPDR - Monthly Subscription - Provisioning
  • WGAEPDR39900 — WatchGuard Advanced EPDR - Monthly Subscription - Provisioning
  • WGARTA39900 — WatchGuard Advanced Reporting Tool - Monthly Subscription - Provisioning
  • WGPMA39900 — WatchGuard Patch Management - Monthly Subscription - Provisioning
  • WGFEA39900 — WatchGuard Full Encryption - Monthly Subscription - Provisioning
  • WGDCA39900 — WatchGuard Data Control - Monthly Subscription - Provisioning
  • WGSFA39900 — WatchGuard SIEMFeeder - Monthly Subscription - Provisioning

When WatchGuard bills you monthly for a software product, your invoice includes a SKU that reflects the product license usage for that month.

For physical hardware orders, the distributor also specifies whether the order is a drop-ship order.

To create purchase orders, you can make calls to the /PurchaseOrders endpoint in the Product Order API. For more information, see Create a New Purchase Order.

Step 3 — WatchGuard Creates a Subscription Contract

When WatchGuard receives a purchase order from a distributor, we create a subscription contract. If the distributor uses the Product Order API to create the purchase order, the API creates the subscription contract automatically.

Subscription contracts include detailed information for the order and billing details, such as the contract term, total cost, remaining balance, billing start and end dates, and more.

WatchGuard does not start to bill the distributor for a subscription contract until the billing start date, which is 15 days after the creation of the subscription contract. For physical hardware subscriptions, this grace period provides time for the distributor to fulfill the order and ship the device to the partner.

To make calls to the Product Order API to query subscription contracts, see Get Subscription Contracts.

Step 4 — Distributor Assigns a Serial Number to the Contract (Physical Hardware Subscriptions Only)

Each Firebox or Access Point has a unique serial number that identifies the device. Hardware subscription contracts must include the serial numbers of any devices they cover.

For virtual hardware devices (FireboxV and Firebox Cloud), WatchGuard automatically assigns a serial number to the subscription contract when it is created.

For physical hardware devices:

• For drop-ship orders that WatchGuard fulfills on behalf of the distributor, WatchGuard assigns the serial numbers of devices to subscription contracts when the devices ship from our warehouse.

Only distributors that are authorized for drop-ship can submit drop-ship orders.

• For orders that the distributor fulfills, the distributor must note the serial numbers of the devices it sent to the partner and assign them to the subscription contracts. If the distributor does not assign a serial number to a hardware subscription contract, the contract status changes to Cancelled automatically when the grace period ends.

To assign a serial number to a physical hardware subscription contract, you can make a request to the /Contracts/{subscriptionContractId}/SerialNumber endpoint. For more information, see Assign a Serial Number to a Contract.

Serial numbers apply only to hardware contracts. For software contracts, WatchGuard automatically generates a software license key for the contract when it is created.

Step 5 — WatchGuard Invoices the Distributor

When WatchGuard receives a purchase order from a distributor and creates a subscription contract, we do not start to bill the distributor immediately. Billing starts 15 days after the creation of the subscription contract. The amount of time between the order date and the billing start date is the Grace Period. Partners can activate and use the software or device in the grace period.

WatchGuard invoices distributors on the 1st of each month. We no longer invoice distributors on the 15th of the month. For both hardware and software subscriptions, the first invoice cycle starts on the 1st of the next month after the distributor submits the purchase order. For example, if the distributor submits a purchase order on 2 April, billing starts 15 days later on 17 April, and the first invoice is generated on 1 May.

After the first invoice, WatchGuard continues to generate invoices for the amount owed each month of the subscription contract.

The payment terms agreed between WatchGuard and the distributor determine the due date for the invoice. For example, if the payment terms are Net 30, the due date is 30 days after the invoice date.

WatchGuard does not send separate invoices for each subscription contract. Instead, we include all invoices with the same invoice date on a single consolidated invoice. Each line item on the consolidated invoice represents an invoice for a specific billing period for a specific subscription contract. The line item includes the subscription contract ID, product SKU and description, quantity, term, term rate, and net amount for the contract.

To make calls to the Product Order API to query invoices, see Invoices.

Distributors should not use invoices to see a consolidated view of all their subscription contracts, because invoices do not include lines for canceled contracts, or contracts billed on a different invoice cycle. To view all subscription contracts, see Get Subscription Contracts.

Optional — Distributor Cancels Contracts

Distributors can cancel subscription contracts when there is a problem, such as when a partner stops payments for a product or cancels an order. Cancellations take effect at the end of the month.

Customers cannot activate devices that are associated with canceled subscription contracts. If a distributor cancels a contract before the associated device is activated, the distributor can associate the device with a new subscription contract, and then activate it.

To cancel a subscription contract, you can make a request to the /Contracts/{subscriptionContractId}/Cancel endpoint. For more information, see Cancel Subscription Contracts.

WatchGuard checks the status of all subscription contracts every month:

• Software subscriptions — WatchGuard extends the expiration date of product license keys for contracts that are not canceled. When a software subscription contract status is Cancelled, product license keys for the contract expire on the next contract billing date.

• Hardware subscriptions — WatchGuard extends the feature key expiration date for devices with contracts that are not canceled. When a hardware subscription contract status is Cancelled, the device feature key expires. When the feature key expires:

  • Fireboxes — Only one client can pass traffic through the device. Subscription services, such as WebBlocker, no longer work. The Firebox retains its configuration.

  • Access Points — All SSIDs are disabled. Subscription services, such as VPN to Firebox, no longer work. The AP retains its configuration.

  Devices with canceled subscription contracts continue to try to download an extended feature key from WatchGuard every day — APs try once a day and Fireboxes twice a day. Users can also manually check for an extended feature key.

WatchGuard invoices distributors for canceled contracts differently based on the contract term:

• One month contracts — When a distributor cancels a one month contract, WatchGuard does not send any more invoices to the distributor.
• Three year contracts (hardware subscriptions only) — When a distributor cancels a three year contract, WatchGuard continues to invoice the distributor until the end of the three year subscription term. When the three year subscription term ends, the contract changes to a one month contract.

Optional — Distributors Retrieve Drop-Ship Details

For drop-ship orders that WatchGuard fulfills on behalf of the distributor, distributors can make a request to the /Contracts/DropShipInfo/{subscriptionContractId} endpoint to retrieve shipping information and other details for the order. For more information, see Get Drop-Ship Order Details.

Only distributors that are authorized for drop-ship can submit drop-ship orders.

Optional — Distributors Retrieve License Usage Details

After partners complete their orders and their customers start to use WatchGuard products, distributors can retrieve license usage information for a specific time range through the Product Order API. The API can return license usage data for all partner accounts, for a specific partner account, or for a specific subscription contract. You can also choose whether to include license usage details for each customer (tenant) account in the response.

For example, you could retrieve license usage details for a partner for all subscription contracts in a specific month.

To retrieve license usage information, you can make a request to the /Contracts/UsageDetails endpoint. For more information, see Get License Usage Details.

Getting Started

This section describes how to submit requests to the Product Order API.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. OAuth is an open standard that provides secure access to protected resources.

To request an access token, you send a request to the WatchGuard Authentication API. The request must include the API access credentials you received from WatchGuard, encoded into base64. The string to encode must be in the form: access_id:access_pwd.

After you receive an access token, include the access token and your API key in the header of all requests to the Product Order API.

Request an Access Token

To get an access token from the WatchGuard Authentication API, make a request to the /oauth/token endpoint.

Request URL

The URL you use to request an access token depends on the environment:

• Staging — https://api.staging.<region>.cloud.watchguard.com/oauth/token
• Production — https://api.<region>.cloud.watchguard.com/oauth/token

Request Headers

Request Body

Example Request

curl -X POST https://api.usa.cloud.watchguard.com/oauth/token \ 
	-H 'accept: application/json' \
	-H 'Authorization: Basic dXNlcm5hbWU6N3loVHI1RHNkLWg2YTktODVnZS1nNjc4OTNoNmUwdGQ' \ 
	-H 'Content-Type: application/x-www-form-urlencoded' \
	-d 'grant_type=client_credentials&scope=api-access'

Example Response

{
	"access_token": "eyJraWQiOiJNWnpabklNK2V6Q3BXUE...",
	"token_type": "Bearer",
	"expires_in": 3600,
	"scope": "api-access",
}

The response contains this information:

When you make an API request, include your access token in the Authorization header parameter and your API access key in the WatchGuard-API-Key parameter. For example:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Invoices/1000986 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Access Token Expiration

When you generate an access token, the token is valid for 3600 seconds (1 hour).

You can reuse the same token in public API requests until it expires, then you must request a new token. If you use an expired token in a request, the response contains the 401 Unauthorized status code.

Use one of these methods to determine when to request a new access token:

• Keep track of the time since you received a token, and request a new token before the number of seconds in the expires_in field for the current token reaches zero.
• Request a new token after you receive the 401 Unauthorized status code that indicates the current token is expired.

HTTP Requests

Use these components to construct HTTP requests to the Product Order API:

https://api.usa.cloud.watchguard.com/rest/orders/subscriptions/v1/Invoices

https://api.usa.cloud.watchguard.com/rest/orders/subscriptions/v1/Contracts/{subscriptionContractId}/SerialNumber

?startDate=2019-01-01&endDate=2019-02-01

curl -X GET https://api.usa.cloud.watchguard.com/rest/orders/subscriptions/v1/Products?model=M370&serviceSuite=Total%20Security \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 

-d {
	"purchaseOrderNumber": "124598-7845",
	"resellerId": "ACC-1235467",
	"lineItems": [
		{
		"sku": "WGM37933"
		}
	]
}

Example Requests

This request to the /Products endpoint returns products for the M370 Firebox model:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Products?model=M370 \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 

This request to the /Invoices/{InvoiceNumber} endpoint returns details of a specific invoice:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Invoices/1000986521456 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'  

This request to the /PurchaseOrders endpoint creates a new purchase order:

curl -X POST https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/PurchaseOrders \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' \
	-d '{
	 "purchaseOrderNumber": "123421-896",
	 "resellerId": "ACC-12345786",
	 "isDropShipOrder": "false",			
	 "lineItems": 
 		[ 
		{ "sku": "WGM37933" } 
		]
	    }'

Status and Error Codes

WatchGuard public APIs use HTTP status codes to indicate the success or failure of a request:

API Responses

Some calls to the Product Order API return data in the response body in JSON format.

For example, if you make a request to the /Contracts/{subscriptionContractId} endpoint, the response body includes details of the requested subscription contract:

{
	"subscriptionContractId": "SB000015439",
	"distributorId": "WGTESTDISTI",
	"resellerId": "ACC-1234569",
	"subscriptionStatus": "Active",
	"purchaseOrderNumber": "12456987",
	"purchaseOrderReceivedDate": "2019-02-15T00:00:00+00:00",
	"serviceSku": "WGM37933",
	"invoiceSkuDescription": "WatchGuard Firebox M370 with 3-yr Total Security Suite Monthly Subscription",
	"applianceSku": "",
	"serialNumber": "",
	"serialNumberReceivedDate": "1900-01-01T00:00:00+00:00",
	"totalSubscriptionTermCost": 4989.6,
	"termInMonths": 36,
	"termBillingStartDate": "2019-03-15T00:00:00+00:00",
	"termBillingEndDate": "2022-03-14T00:00:00+00:00",
	"termInvoicesPosted": 0,
	"totalTermChargesInvoiced": 0,
	"remainingInvoicesForTerm": 36,
	"remainingBalance": 4989.6,
	"totalExtensionInvoices": 0,
	"totalExtensionChargesInvoiced": 0,
	"totalSubscriptionLifetimeCost": 0,
	"userCount": 0
}

For detailed information about responses for each endpoint, see the API specification.

Pagination

Some GET endpoints that return a list of objects support pagination through the take and skip request parameters:

You can use these parameters to construct queries for pages of results. For example, this request returns results 11–20 from the list of objects:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Invoices?take=10&skip=10 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 

Products

Products are items that distributors can order from WatchGuard. You can use the Product Order API to get product data from the WatchGuard product catalog.

Query the WatchGuard Product Catalog

The WatchGuard product catalog includes details of all products that distributors can order from WatchGuard.

To request data from the product catalog to integrate with your online portal, you can make GET requests to these API endpoints:

You could use the response data from calls to these endpoints to populate drop-down lists in an order page on your online portal. For example, this request returns all models in the WatchGuard product catalog:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Products/Models \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

When a partner selects options from the drop-down lists and searches for product matches, you could then construct a filtered request to the Products endpoint to return the relevant products from the WatchGuard product catalog.

Example Request

To get available products for the Firebox M370 model with the Total Security service suite, make this request to the Products endpoint:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Products?model=M370&serviceSuite=Total%20Security \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

In response to the example request, the API returns details of two products from the WatchGuard product catalog in the response body. The products have different contract terms (Monthly and 3 Years).

{
	"results": [
	{
	"description": "WatchGuard Firebox M370 with 3-yr Total Security Suite Monthly Subscription",
	"category": "Network Security > Firebox",
	"family": "M-Series",
	"model": "M370",
	"sku": "WGM37933",
	"serviceSuite": "Total Security",
	"classification": "Subscription",
	"contractTerm": "3-yr",
	"invoicingFrequency": "Monthly",
	"msrp": 231,
	"region": "Regionless",
	"dimensions": "N/A",
	"weight": "N/A",
	"marketingText": "WatchGuard Firebox M370 appliances combine strong security, high performance...",
	"imageUrls": [
		"https://p.widencdn.net/xx9ujc/M370_F_new",
		"..."
		],
	"keySellingPoints": [
		"Firewall throughput of 8 Gbps to keep traffic moving, with the best UTM throughput...",
		"Latest generation multi-core processors provide the power to run all security scanning...",
		"..."
		],
	"dataSheetUrl": "https://content.etilize.com/Manufacturer-Brochure/1040534011.pdf",
	"pricingCategory": "P",
	"upc": "654522031341",
	"embedUrls": [
		"https://embed.widencdn.net/img/watchguard/vqf6ink7xa/640px/M370_F_new.jpeg",
		"..."
		]
	},
	{
	"description": "WatchGuard Firebox M370 with 1-month Total Security Suite Subscription",
	"category": "Network Security > Firebox",
	"family": "M-Series",
	"model": "M370",
	"sku": "WGM37938",
	"serviceSuite": "Total Security",
	"classification": "Subscription",
	"contractTerm": "1-mo",
	"invoicingFrequency": "Monthly",
	"msrp": 269,
	"region": "Regionless",
	"dimensions": "N/A",
	"weight": "N/A",
	"marketingText": "WatchGuard Firebox M370 appliances combine strong security, high performance...",
	"imageUrls": [
		"https://p.widencdn.net/xx9ujc/M370_F_new",
		"..."
		],
	"keySellingPoints": [
		"Firewall throughput of 8 Gbps to keep traffic moving, with the best UTM throughput...",
		"Latest generation multi-core processors provide the power to run all security scanning...",
		"..."
		],
	"dataSheetUrl": "https://p.widencdn.net/6izrhp/Datasheet_M200_M370",
	"pricingCategory": "P",
	"upc": "654522031358",
	"embedUrls": [
	"https://embed.widencdn.net/img/watchguard/vqf6ink7xa/640px/M370_F_new.jpeg",
		"..."
		]
	}
]
}

Purchase Orders

Purchase orders include details of the products distributors want to order from the WatchGuard product catalog. You can use the Product Order API to submit purchase orders to WatchGuard.

Create a New Purchase Order

After the partner selects products on your portal and submits an order, you must create a new purchase order. Purchase orders include details of the products you want to order from the WatchGuard product catalog. WatchGuard uses the information from the purchase order to generate a subscription contract.

If you want WatchGuard to fulfill a hardware order on your behalf and ship devices directly to the partner, you must set the isDropShipOrder parameter to true and include shipping information in the dropShipOrderInfo parameters.

To create a new purchase order and send it to WatchGuard, you must submit a request to the /PurchaseOrders endpoint.

The JSON request body must include these purchaseOrderRequest parameters:

Example Request

This request to the PurchaseOrders endpoint creates a new purchase order for two hardware products that WatchGuard will fulfill on behalf of the distributor and drop-ship directly to the partner:

curl -X POST https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/PurchaseOrders \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' \
	-d '{
		"purchaseOrderNumber": "55498745",
		"resellerId": "ACC-4593211",
		"isDropShipOrder": true,
		"dropShipOrderInfo": {
			"companyName": "Example Company",
			"contactName": "Maria Rodriguez",
			"carrierAccountNumber": "123456789",
			"shipMethod": "FEDEX GROUND",
			"phoneNumber": "1234567890",
			"phoneExtension": "1",
			"emailAddress": "[email protected]",
			"shipToAddress": {
			"streetAddress1": "505 5th Avenue South",
			"streetAddress2": "Suite 500",
			"streetAddress3": "",
			"city": "Seattle",
			"state": "WA",
			"postalCode": "98104",
			"country": "United States"
			}
		},		
		"lineItems": [
			{ 
			"sku": "WGM37933" 
			},
			{
			"sku": "WGM37938" 
			} 
			]
		}'	

Example Response

If the API successfully creates a purchase order, it returns a 200 status code and the new purchase order object. In the lineItems array, the subscriptionContractId parameter in each line item includes the generated subscription contract IDs for each product ordered.

{
"purchaseOrderNumber": "55498745",
"resellerId": "ACC-4593211",
"lineItems": [
		{
		"sku": "WGM37933",
		"subscriptionContractId": "SB000015755"
		},
		{
		"sku": "WGM37938",
		"subscriptionContractId": "SB000015756"
		}
	]
}

If the API successfully creates a purchase order, but WatchGuard could not automatically generate a license key for a software product in the order, the API returns a 202 status code. In the response, the activationStatus parameter for the software product line item includes the text "Failed. Auto-provisioning error. Please contact WatchGuard Customer Care." To activate the software product, contact WatchGuard Customer Care.

{
"purchaseOrderNumber": "PO12345",
"resellerId": "ACC-12345678",
"lineItems": [
		{
		"sku": "WGM11111",
		"subscriptionContractId": "132456"
		"activationStatus": "Failed. Auto-provisioning error. Please contact WatchGuard Customer Care."
		}
		]
}

If the purchase order number already exists, the API returns a 400 Bad Request error code with DistributorPoAlreadyUsed in the response body.

If a subscription contract already exists for the specified partner and product SKU, the API returns a 400 Bad Request error code with Contract already exists for Reseller/SKU combination in the response body.

If the specified resellerId does not match the resellerId of an existing partner, the API returns a 400 Bad Request error code with Invalid reseller in the response body.

If the specified sku does not match the SKU of a product in the WatchGuard product catalog, the API returns a 400 Bad Request error code with Invalid sku in the response body.

If you are not authorized to create drop-ship orders, and the isDropShipOrder parameter in the request is true, the API returns a 400 Bad Request error code with This distributor is not authorized for drop ship. A distributor must be authorized for drop ship. in the response body. If you are a distributor who wants to create drop-ship orders, contact [email protected].

If you try to create a drop-ship order for a software product SKU, the API returns a 400 Bad Request error code with Software Subscription Services cannot be drop shipped. in the response body.

If you try to create a drop-ship order for a virtual Firebox product SKU, the API returns a 400 Bad Request error code with DropShip is not valid for FireboxV or Firebox Cloud SKUs. in the response body.

For requests to create purchase orders that include many line items, such as all WatchGuard Endpoint Security products and modules, the Product Order API might sometimes return a 504 Gateway Timeout error with the message Endpoint request timed out. This error does not necessarily indicate that the request failed — the Product Order API might continue to process the request, create the purchase order, and then create the related subscription contracts. To verify the creation of the subscription contracts, wait one or two minutes, then submit a request to the /Contracts endpoint and include the skip request parameter to return the most recent contracts. You can use the purchaseOrderNumber and resellerID parameters in the subscription contract response to verify that a subscription contract was created for your purchase order. If the Product Order API does not create subscription contracts for the request, contact Customer Care.

Subscription Contracts

Subscription contracts include details of a subscription purchased by a partner for a WatchGuard product. You can use the Product Order API to retrieve subscription contracts. You can also cancel subscription contracts, and get license usage information for specific partners or subscription contracts.

For physical hardware subscriptions, you can also assign device serial numbers to subscription contracts.

Get Subscription Contracts

Some information in a subscription contract can change over time. For example, the remaining balance on a three year contract falls as you make monthly payments.

If you want to see the latest details of one or more subscription contracts, you can make calls to the Product Order API to request the information from the WatchGuard database.

Get Subscription Contract Summaries

To get summaries of your subscription contracts from the Product Order API, make a request to the /Contracts endpoint.

To filter the results by the dates the subscription contracts were created or by purchase order, include the optional firstCreationDate, lastCreationDate, and purchaseOrderNumber request parameters:

For more information about the take and skip request parameters, see Pagination.

Example Request

This request gets summaries of all subscription contracts that were created in January 2024:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts?firstCreationDate=01-01-2024&lastCreationDate=01-31-2024 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response body includes a summary of the subscription contracts:

{
	"results": [{
		"subscriptionContractId": "SB000015591",
		"purchaseOrderNumber": "PO1122344558",
		"sku": "WGM37923",
		"skuDescription": "WatchGuard Firebox M370 with 3-yr Basic Security Suite Monthly Subscription",
		"serialNumber": "",
		"createdDate": "2024-01-11T18:54:46.685Z",
		"startDate": "2024-01-11T18:54:46.685Z",
		"endDate": "2027-01-11T00:00:00+00:00"
		},
		{...},
		{...}
	],
	"totalCount": "3"
}

Get Specific Subscription Contract Details

To request detailed information for a specific subscription contract, send a request to the /Contracts/{subscriptionContractId} endpoint. The request path must include the {subscriptionContractId} path parameter:

Example Request

This request gets the subscription contract with the ID of SB000015439:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts/SB000015439 \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 

Example Response

The response body includes full details of the subscription contract:

{
	"subscriptionContractId": "SB000015439",
	"distributorId": "WGTESTDISTI",
	"resellerId": "ACC-887711223",
	"subscriptionStatus": "PreFulfillment",
	"purchaseOrderNumber": "P574987202580",
	"purchaseOrderReceivedDate": "2019-03-22T00:00:00+00:00",
	"serviceSku": "WGM37923",
	"invoiceSkuDescription": "SB000015439 - 05/01/2019 - 04/30/2022 - 36",
	"applianceSku": "WGM37900",
	"serialNumber": "",
	"totalSubscriptionTermCost": 3110.4,
	"termInMonths": 36,
	"termBillingStartDate": "2019-05-01T00:00:00+00:00",
	"termBillingEndDate": "2022-04-30T00:00:00+00:00",
	"termInvoicesPosted": 0,
	"totalTermChargesInvoiced": 0,
	"remainingInvoicesForTerm": 36,
	"remainingBalance": 3110.4,
	"totalExtensionInvoices": 0,
	"totalExtensionChargesInvoiced": 0,
	"totalSubscriptionLifetimeCost": 0,
	"userCount": 0				
}

For software subscriptions, the userCount parameter in the response shows the current number of subscription users for the software. For hardware subscriptions, the parameter always shows 0.

If the specified subscriptionContractId does not exist, the API returns the 404 Not Found status code.

If the specified subscriptionContractId is not in the valid format, the API returns the 400 status code.

Assign a Serial Number to a Subscription Contract (Physical Hardware Subscriptions)

Each hardware device is identified by a unique serial number, which appears on the back of the device.

After you create a new purchase order for a physical hardware subscription, the Product Order API automatically generates a new subscription contract for each device in the order. However, because it might take a few days to fulfill the order, the subscription contract does not yet include the serial number of the actual device that you will send to the partner.

After you ship a device from your warehouse to the partner, you can make a call to the Product Order API to add the serial number of the device to the associated subscription contract.

Do not make a request to this endpoint to assign a serial number to a virtual Firebox (FireboxV or Firebox Cloud). WatchGuard automatically assigns a serial number to subscription contracts for virtual Fireboxes.

Do not make a request to this endpoint to assign a serial number to a subscription contract for a drop-ship order. WatchGuard assigns the serial number to subscription contracts for drop-ship orders when we ship the devices from our warehouse to the partner.

To add a serial number to a subscription contract, make a request to the /Contracts/{subscriptionContractId}/SerialNumber endpoint.

In the subscriptionContractId path parameter, you must include the ID of the subscription contract object you want to assign the serial number to:

The request body must include the serial number in the serialNumber parameter:

If you do not assign a device serial number to the physical hardware subscription contract, WatchGuard cancels the contract automatically when the grace period ends.

Example Request

This request assigns the serial number DDD3321234678 to the subscription contract SB000015439:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts/SB000015439/SerialNumber \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' \
	 -d '{
		"serialNumber": "DDD3321234678"
	}'

Example Response

If the API successfully updates the subscription contract, it returns a 204 Success status code.

If the subscription contract specified in the subscriptionContractId path parameter does not exist, the API returns the 404 Not Found error code.

If the serial number specified in the request body serialNumber parameter is not a valid serial number for a WatchGuard device in your inventory, the API returns the 400 Bad Request error code with SerialNumberNotFound in the response body.

If the serial number specified in the request body serialNumber parameter is not in the correct format, the API returns a 400 error code with 'serial Number' is not in the correct format in the response body.

If you try to assign a serial number to a subscription contract for a software product or virtual Firebox, the API returns a 400 error code with Cannot assign Serial Number to a Software, FireboxV, or Firebox Cloud contract. in the response body.

Cancel Subscription Contracts

You can cancel an active subscription contract if there is a problem, such as when a customer stops payments for a device or cancels an order. Cancellations take effect at the end of the month.

To cancel a subscription contract, send a request to the /Contracts/{subscriptionContractId}/Cancel endpoint.

The request path must include the subscriptionContractId path parameter:

The request body must include the cancelReason parameter:

{
"cancelReason": "OrderError"
}

Customers cannot activate devices that are associated with canceled subscription contracts. If a distributor cancels a contract before the associated device is activated, the distributor can then associate the device with a new subscription contract, and activate it.

Example Request

This request cancels the subscription contract SB000015439 because of an error with the order:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts/SB000015439/Cancel \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' \
	-d '{
		"cancelReason": "OrderError"
	    }'

Example Response

If the request succeeds, the server responds with a 204 Success status code and sets the value of the subscriptionStatus parameter in the specified subscription contract object to Cancelled.

If the specified subscriptionContractId does not exist, the API returns the 404 Not Found status code.

If the specified subscriptionContractId is already canceled, the API returns a 400 status code with SubscriptionNotActive in the response body.

Get License Usage Details

Because of a known issue, the /Contracts/UsageDetails endpoint might not return accurate license usage information for subscriptions created before April 2023.

You can retrieve license usage information for subscription contracts, so that you can see how many licenses a partner used in a specified time period. The response includes usage details for the first day of the month and any other date that usage changed during the specified time period.

To retrieve license usage details, send a request to the /Contracts/UsageDetails endpoint.

You can request license usage information for specific partners and specific subscription contracts. You can also choose whether to show usage details broken down for specific customer (tenant) accounts.

When you send a request to this endpoint, you can include these request parameters:

For more information about the Take and Skip request parameters, see Pagination.

Example Request

This request gets license usage details for subscription contracts for February and March 2024. The response will include data for customer accounts.

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts/UsageDetails?startDate=022024&endDate=032024&tenantUsage=true \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response body includes details of the license usage.

  "pagination": {
    "totalCount": 1,
    "skip": 0,
    "take": 1
  },
  "contracts": [
    {
      "subscriptionContractId": "SB000015591",
      "resellerId": "ACC-887711223",
      "productDescription": "WatchGuard AuthPoint Subscription Provisioning",
      "usage": [
        {
          "usageDate": "2024-02-01T00:00:00+00:00",
          "totalCount": 8,
          "customers": [
            {
              "endCustomerId": "WGC-1-298354e4f95a2091b248",
              "endCustomerName": "Example Customer",
              "userCount": 0,
              "delegatedAllocation": false
            },
            {
              "endCustomerId": "WGC-1-309263e3f87a1907a756",
              "endCustomerName": "Example Customer 2",
              "userCount": 8,
              "delegatedAllocation": false
            }
          ]
        },
        {
          "usageDate": "2024-02-11T00:00:00+00:00",
          "totalCount": 10,
          "customers": [
            {
              "endCustomerId": "WGC-1-298354e4f95a2091b248",
              "endCustomerName": "Example Customer",
              "userCount": 2,
              "delegatedAllocation": false
            },
            {
              "endCustomerId": "WGC-1-309263e3f87a1907a756",
              "endCustomerName": "Example Customer 2",
              "userCount": 8,
              "delegatedAllocation": false
            }
          ]
        },
        {
          "usageDate": "2024-02-26T00:00:00+00:00",
          "totalCount": 8,
          "customers": [
            {
              "endCustomerId": "WGC-1-309263e3f87a1907a756",
              "endCustomerName": "Example Customer 2",
              "userCount": 8,
              "delegatedAllocation": false
            }
          ]
        }
      ]
    }
  ]
}

Get Drop-Ship Order Details

Drop-ship orders are orders that WatchGuard fulfills on behalf of a distributor. When you create a new purchase order, you can use the isDropShipOrder parameter to specify if the order will be drop-shipped. For more information, see Create a New Purchase Order.

To retrieve shipping information and other details for a drop-ship order, send a request to the /Contracts/DropShipInfo/{subscriptionContractId} endpoint.

When you send a request to this endpoint, you must include this request parameter:

Example Request

This request gets drop-ship order details for subscription contract SB000015439.

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Contracts/DropShipInfo/SB000015439 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response body includes the drop-ship order details for the specified subscription contract.

{
  "shippingTrackingNumber": "9610 1385 2890",
  "shipMethod": "FEDEX GROUND",
  "companyName": "Example Company",
  "contactName": "Maria Rodriguez",
  "carrierAccountNumber": "123456789",
  "PhoneExtension": "1",
  "PhoneNumber": "1234567890",
  "SerialNumber": "108302A94PT4H",
  "OrderNumber": "55498745",
  "shipToAddress": {
    "streetAddress1": "505 5th Avenue South",
    "streetAddress2": "Suite 500",
    "streetAddress3": "",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98104",
    "country": "United States"
  }
}

Invoices

Invoices are statements of the amount of money owed by a distributor. You can use the Product Order API to retrieve invoices.

WatchGuard invoices distributors monthly for any active subscription contracts. You can get details of your invoices from the Product Order API.

WatchGuard includes all invoices with the same invoice date on a single consolidated invoice. Each line item on the consolidated invoice represents an invoice for a specific billing period of a specific subscription contract.

Distributors should not use invoices to view all of their subscription contracts, because invoices do not include lines for suspended or canceled subscription contracts, or subscription contracts billed on a different invoice cycle.

Get Invoice Summaries

To get summaries of your consolidated invoices, send a request to the /Invoices endpoint. To filter the results by invoice date, include the optional startDate and endDate request parameters.

You can also use the take and skip request parameters to request pages of results. For more information, see Pagination.

Example Request

This request gets all consolidated invoices with an invoice date in January 2019:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Invoices?startDate=01-01-2019&endDate=01-31-2019 \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL' 

Example Response

The response body includes summaries of the requested consolidated invoices in the summaries array:

{
"totalRowCount": 1,
"summaries": [
	{
	"invoiceNumber": "SBINV0000000046",
	"invoiceDate": "2019-03-26T00:00:00+00:00",
	"dueDate": "2019-05-10T00:00:00+00:00",
	"purchaseOrderNumber": "TBD",
	"paymentTerms": "1% 15, Net 45 Days",
	"total": 403.2
	}
	]
}

Get Specific Invoice Details

To request details of a specific consolidated invoice, send a request to the /Invoices/{InvoiceNumber} endpoint. The request path must include the invoiceNumber path parameter:

Example Request

This request gets the consolidated invoice with an invoice ID of SBINV0000000046:

curl -X GET https://api.usa.cloud.watchguard.com/rest/Orders/Subscriptions/v1/Invoices/SBINV0000000046 \ 
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...' \
	-H 'Content-Type: application/json' \
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response body includes details of the consolidated invoice. The lineItems array includes separate items for each invoice that is included in the consolidated invoice.

{
	"invoiceNumber": "SBINV0000000046",
	"invoiceDate": "2019-03-26T00:00:00+00:00",
	"dueDate": "2019-05-10T00:00:00+00:00",
	"billToAddress": {
	"addressLine1": "44299 Nobel Drive",
	"addressLine2": "",
	"addressLine3": "",
	"city": "Fremont",
	"state": "CA",
	"zipCode": "94538",
	"country": "UNITED STATES",
	"phoneNumber": "51055512129999"
	},
	"watchGuardAddress": {
	"addressLine1": "505 5th Ave S Ste 500",
	"addressLine2": "",
	"addressLine3": "",
	"city": "Seattle",
	"state": "WA",
	"zipCode": "98104-3892",
	"country": "UNITED STATES",
	"phoneNumber": "00000000000000"
	},
	"billToDistributorName": "WG Test Distributor",
	"purchaseOrderNumber": "TBD",
	"paymentTerms": "1% 15, Net 45 Days",
	"lineItems": [
		{
		"subscriptionContractId": "SB000015652",
		"sku": "WGM37913",
		"description": "WatchGuard Firebox M370 with 3-yr Standard Support Monthly Subscription",
		"serialNumber": "",
		"quantity": 1,
		"unitPrice": 50.4,
		"markdown": 0,
		"extendendPrice": 0,
		"billingStartDate": "2019-03-01T00:00:00+00:00",
		"billingEndDate": "2019-03-31T00:00:00+00:00"
		},
		{
		"subscriptionContractId": "SB000015652",
		"sku": "WGM37913",
		"description": "WatchGuard Firebox M370 with 3-yr Standard Support Monthly Subscription",
		"serialNumber": "",
		"quantity": 1,
		"unitPrice": 50.4,
		"markdown": 0,
		"extendendPrice": 0,
		"billingStartDate": "2019-04-01T00:00:00+00:00",
		"billingEndDate": "2019-04-30T00:00:00+00:00"
		}
	]
}

For software products, the sku parameter includes a SKU that reflects the product license usage for that month.