WMS Acquisitions API v1 transition resources
The WMS Acquisitions API (v1) lets libraries and vendors integrate WorldShare Acquisitions data, such as purchase orders and invoices, with local systems like accounting and ERP platforms. Version 2 of the API is now available at a new endpoint with modern authentication, more consistent data, and better logging and monitoring.
If your application uses v1, we encourage you to start planning your move to v2. v2 does not yet cover every v1 capability, so please review Current gaps and limitations before you start.
About WMS Acquisitions API v2
Consistent field names. Field naming is aligned across endpoints, so the same concept uses the same name whether you are working with orders or order items.
Better filtering. The order and order item search endpoints support filtering by created, modified, and placed date, including date ranges.
ISO date strings. All dates are returned and accepted as ISO 8601 strings.
Controlled access to budgets. v2 fully supports controlled access to budgets, so your application only sees the budgets and funds the authenticated user is permitted to use.
Open access workflows. v2 supports open access workflows, such as article processing charge (APC) requests. You can create, search, update, delete and invoice open access requests. v1 has no equivalent.
Item request workflows. v2 supports item request workflows, such as purchase requests. You can create, read and update requested items. v1 has no equivalent.
Granular scopes. v1 used a single scope for everything. v2 scopes are specific to the task, such as viewing orders versus managing them, so you can give each WSKey only the access it needs.
Easier troubleshooting and support. v2 has more robust logging and monitoring, which helps OCLC Support and your team diagnose and resolve problems faster.
What is changing
Moving to v2 means updating your authentication setup, your endpoint URLs, and the way your code reads and writes data.
Authentication
HMAC authentication is no longer supported in v2. Applications must request an OAuth 2.0 access token and send it as a bearer token with each request. If your v1 integration signs requests with HMAC, that part of your code needs to be replaced, not just reconfigured. If you are already using OAuth 2.0 with v1, your token request stays the same except for the scopes you request. Tokens are issued by https://oauth.oclc.org/token using the client credentials or authorization code grant.
WSKey scopes
v1 used a single scope, WMS_ACQ. v2 replaces it with a set of WMS_Acquisitions scopes. Your WSKey must be provisioned with the scopes for the operations your application performs.
| v2 scope | Allows |
|---|---|
| WMS_Acquisitions:view_orders | Search and read orders and order items |
| WMS_Acquisitions:manage_orders | Create and update orders; create order items |
| WMS_Acquisitions:submit_orders | Submit orders |
| WMS_Acquisitions:view_budgets_funds | Read budgets and funds |
| WMS_Acquisitions:view_departments | Read departments |
| WMS_Acquisitions:view_addresses | Read institution addresses |
| WMS_Acquisitions:view_requests | Read requested items |
| WMS_Acquisitions:create_requests | Create requested items |
| WMS_Acquisitions:manage_requests | Update requested items |
| WMS_Acquisitions:read_open_access_request | Search and read open access requests |
| WMS_Acquisitions:manage_open_access_request | Create and update open access requests |
| WMS_Acquisitions:delete_open_access_request | Delete open access requests |
| WMS_Acquisitions:invoice_open_access_request | Invoice open access requests |
Existing WSKeys with the WMS_ACQ scope are not carried over to v2. To use v2, request a new WSKey for the WMS Acquisitions API v2 with the scopes your application needs.
Endpoint URLs
| URL | |
|---|---|
| v1 | https://{registry}.share.worldcat.org/acquisitions/* or https://acq.sd0X.worldcat.org/* |
| v2 | https://management.api.oclc.org/acquisitions/* |
v1 URLs were specific to your institution or data center. v2 uses a single URL for everyone, and your institution is identified by your access token rather than the host name. Currently, all v2 calls are routed to the US data center, whereas v1 calls were routed to the data center that hosts your institution's data. This API will transition to regional URLs in the near future. The current URL will remain backward compatible for some time, so you will not need to change your integration immediately when regional URLs are introduced.
Endpoint and data changes
| Area | v1 | v2 |
|---|---|---|
| Purchase orders | /acquisitions/purchaseorders | /acquisitions/orders |
| Order items | /acquisitions/purchaseorders/{id}/items | Create: POST /acquisitions/orders/{id}/order-items. Read: GET /acquisitions/order-items/{id}. List and search: GET /acquisitions/order-items, filtered by order.id to list the items on an order. |
| Order submission | PUT /acquisitions/purchaseorders/{id}/submissions | POST /acquisitions/order-submissions |
| Budgets and funds | /acquisitions/budget/data/{id}, /acquisitions/fund/data/{id}, /acquisitions/fund/search | Search budgets: GET /acquisitions/budgets. Search funds in a budget: GET /acquisitions/budgets/{budgetId}/funds. |
| Order identifiers | Purchase order number, such as PO-2012-36 | Order UUID or order number. Both are accepted in the path of order requests. |
| Dates | Varied formats, including epoch timestamps | ISO 8601 date strings |
| Paging | startIndex, itemsPerPage | limit, offset. Responses return entries and a pagination object. |
| Filtering by update time | updatedMin, updatedMax | created.date, modified.date, placed.date ranges, for example now-10d~now-5d |
| Errors | Inconsistent formats | application/problem+json with a messageCode and a requestId |
| Caching | ETag with If-Match on updates | ETag with If-Match on updates, and If-None-Match on reads (returns 304 Not Modified) |
Common field renames on orders:
| v1 field | v2 field |
|---|---|
| purchaseOrderNumber | orderNumber |
| orderName | name |
| purchaseOrderState | state |
| orderItemCount | items |
| totalOrderPrice | total |
| insertTime | created.date |
| lastUpdateTime | modified.date |
| orderDate | placed.date |
| comment | comments |
| customerNumber | accountNumber |
| vendor.vendorId | vendor.id |
| taxCalculationMethod | taxHandling |
| currency, exchangeRate | currencyExchangeRate.code, currencyExchangeRate.rate |
| shipTo, billTo | shipping, billing |
Common field renames on order items:
| v1 field | v2 field |
|---|---|
| resource.worldcatResource and the other resource types | resource, with a type of WORLDCAT, KBWC_COLLECTION, KBWC_ENTRY or LOCAL |
| materialType | resource.materialCode |
| orderType | acquisitionType |
| orderingPrice | unitPrice |
| totalPrice | total |
| bookings and copyConfigs[].booking | funds |
| branchId, shelvingLocationId | location.branchId, location.shelvingLocation |
| requester | requestor |
| insertTime | created.date |
| lastUpdateTime | modified.date |
Current gaps and limitations
Some v1 capabilities are not yet available in v2. If your application depends on them, keep using v1 for those operations until v2 catches up, and watch this page for updates.
Copies. v2 does not yet have a copies endpoint, including receiving copies. This is planned but not yet scheduled.
Invoices. The invoices endpoints are coming soon. Until then, continue to use the v1 invoice endpoints.
Recommended transition path
| Current v1 use | v2 status |
|---|---|
| Create, read, update, and search purchase orders | Available. Use the Orders endpoints. |
| Create, read, and search purchase order items | Available. Use the Order Items endpoints. |
| Submit purchase orders | Available. Use the Order Submissions endpoint. |
| Read budgets and funds | Available. Use the Budgets endpoints. |
| Read, list, and receive purchase order item copies | Not yet available. |
| Create, read, update, and search invoices and invoice items | Coming soon. Continue using v1. |
v2 also includes endpoints that have no v1 equivalent: open access requests, requested items, departments and institution addresses.
Steps to transition
Review the v2 API documentation and the changes above.
Request a new WSKey for WMS Acquisitions API v2 with the WMS_Acquisitions scopes your application needs.
Replace HMAC authentication, if you use it, with an OAuth 2.0 access token request.
Update your base URL to https://management.api.oclc.org.
Update endpoint paths, field names, paging, and date handling in your code.
Test your integration against v2 and check your handling of the new error format.
Use v1 only for copies and invoices until those endpoints are available in v2.
Support for your transition
Our API team is committed to helping you make this move.
Learn from an API expert
OCLC APIs Office Hours. Bring your questions about your transition to OCLC API experts. View past OCLC APIs Office Hours Register for future Office Hours
Help for specific transition tasks
Implementing authentication with the client credentials grant
WMS Acquisitions API v2 technical documentation
WMS Acquisitions API v1 technical documentation
WMS Acquisitions API v1 invoices, budgets, and funds documentation
Personal assistance when you need it