Billing

This document describes APIs that will allow partners to interact with the Onshape billing system.

Please address questions to “api-support@onshape.com” for the fastest response.

Overview

All billing is done through “plans” that are created in the Developer Portal. A “plan” has the following attributes:

Name (also called SKU)	A unique (within your company) plan name
Description	A user-visible description of the plan
Amount	The cost of the plan (may be one-time or recurring, depending on the type)
Type	Monthly, One-time or Consumable

Onshape defines three kinds of plans:

Plan type	Description
Recurring (Monthly Subscription)	A plan that is renewed monthly at a fixed cost. All Apps in the app store must have a Free monthly plan (which is created by default), and may have additional paid plans.
One-time	A plan that is purchased once (not renewed monthly). A user may purchase these multiple times.
Consumable	A plan that represents a consumable unit, such as "hours of rendering" or “simulation runs”. Consumable plans are not fully implemented at this time, but the consumable functionality can be implemented using One-time Purchase plans as described below.

Users may purchase plans through the App Store interface. In addition, if your application has the OAuth Purchase Scope, your application can initiate “in-app” purchases by calling Onshape to request a purchase.

The basic steps for interacting with Onshape Billing:

Define one or more plans using the Developer Portal interface
Use the Onshape API to determine the current user’s plan
Provide features and/or limits based on the current plan

Using the Onshape Billing API

GET /api/accounts/purchases

Returns a list of purchase made by the current user for plans owned by the current application. Use this information to determine what capabilities or features the user is entitled to use.

DELETE /api/accounts/purchases/<purchase id>

Cancel a recurring purchase.

POST /api/accounts/purchases/<purchase id>/consume

Indicate the use of a consumable. (Not fully implemented at this time)

GET /api/billing/plans/client/<client id>

Get a list of the billing plans defined for this client.

Initiating a purchase from an application (in-app purchases)

To initiate a purchase of a subscription or one time item you must set the browser’s location to particular URL within the Onshape stack:

https://cad.onshape.com/billing/purchase?redirectUri=RRRR&clientId=CCCC&sku=SSSS&userId=UUUU

Each of the query parameters should be URL encoded. The clientId is your application’s OAuth Client ID, the sku is the name/sku field for an item (you can find this in the developer portal or it’s retrievable through the /api/billing/plans REST endpoints). The user Id should be the Onshape user Id for the current user and is available through the /api/users/session REST endpoint. The redirectUri is the URI the user will be returned to within your website when the purchase is finished.

When the browser’s location is changed to this pattern the Onshape stack will serve content to confirm the users identity, confirm the details of what is being purchased (or obtained if the item is free) and then after the user agrees to the purchase will confirm the transaction (with our payment processor if the item is not free) and then redirect the user back to the supplied redirectUri (the browser location will be changed to the redirectUri). Additionally Onshape will add a success=true or success=false query parameter to the redirectURI indicating whether the user completed successfully (payment was taken if required etc.) or failed, either due to cancelling the purchase or an issue with payment.

When the browser fetches the redirectUri your application must call back through the /api/account/purchases API to get confirmation of the purchase - do NOT assume that a fetch of the redirectUri with a success=true query parameter actually indicates a purchase has occurred. Query the Onshape stack with the /api/account/purchases API to ensure that the required item has actually been bought.

Consumable Items

A detailed description of the interface for managing consumable purchases will be provided shortly. You can use one-time plans to achieve similar results:

Define a one-time purchase plan with a description indicating the nature of the purchase, for example:
RENDER-10 Ten rendering hours $100
Keep track of the number of hours that the user has consumed. You can store and retrieve this information in Onshape using the following APIs. These APIs allow you to store and retrieve arbitrary information on a per-user basis.
POST /applications/clients/:cid/settings/users/:uid GET /applications/clients/:cid/settings/users/:uid
Check the number of available “units” by getting the purchases and the record of consumables. Be sure to include UI in your application that the user can use to see their remaining quantity.
Alternately, you can store the consumption data in your own system; you do not need to use the Onshape API to manage that data.

Onshape intends to provide a richer set of APIs that help track the purchase and consumption of consumables in the near future.

Other billing models

You can use these mechanisms to implement other models. For example, a time-limited trial could be implemented by scanning purchases for the first “purchase” and denying service if it is more than a defined number of days in the past. A “fixed number of uses per month” could be implemented as a monthly subscription, string usage data with the settings API, and denying service after a fixed number of uses.

Samples

Onshape will provide sample code for both desktop and integrated applications demonstrating the use of the billing APIs and workflow. If you are subscribed to the Onshape Github Partner group, you will have access to those samples as soon as they are posted.

Testing

Please contact api-support@onshape.com to discuss details of testing billing & subscriptions.