Version 12.0.0.20210616

Version 12.0.0.20210616 (2021-06-16)

New API releases

• Gift Cards API and Gift Card Activities API. Gift card support is integrated in the Square Seller Dashboard and the Square Point of Sale application. Sellers can sell, redeem, track, and reload Square gift cards. Now developers can use the Gift Cards API and the Gift Card Activities API to integrate Square gift cards into third-party applications. For more information, see Gift Cards API Overview.

• Cards API. The Cards API replaces the deprecated CreateCustomerCard and DeleteCustomerCard endpoints and lets an application save a customer payment card on file along with other card management operations. For more information, see Cards API Overview.

API updates

• Catalog API:

  • CatalogPricingRule. Support of the customer group discount becomes GA. For more information, see CreateCustomerGroupDiscounts.
  • CatalogItemVariation. Offers Beta support of the stockable and stockable_conversion attributes to enable sales of a product in multiple measurement units.
  • UpsertCatalogObject and BatchUpsertCatalogObjects. Support creating an item with stockable and non-stockable variations with a specified stock conversion between the two. For more information, see Enable Stock Conversion.
  • UpsertCatalogObject and BatchUpsertCatalogObjects. Require that an item be created with at least one variation. Otherwise, an INVALID_REQUEST error is returned.

• Customers API:

  • Using the Customers API to manage cards on file is deprecated:

    • The CreateCustomerCard endpoint is deprecated and replaced by the CreateCard and LinkCustomerToGiftCard endpoints.

    • The DeleteCustomerCard endpoint is deprecated and replaced by the DisableCard and UnlinkCustomerFromGiftCard endpoints.

    • The cards field in the Customer object is deprecated and replaced by the following endpoints:

      • ListCards to retrieve credit and debit cards on file.
      • ListGiftCards to retrieve gift cards on file.

      For more information, see Migrate to the Cards API and Gift Cards API.

    • Customer object. In the cards field, the IDs for gift cards now have a gftc: prefix followed by the card number. This is a service-level change that applies to all Square API versions.

• Disputes API:

  • The Disputes API is now GA.
  • RemoveDisputeEvidence. Renamed to DeleteDisputeEvidence.
  • CreateDisputeEvidenceFile. The URL is changed from /v2/disputes/{dispute_id}/evidence_file to /v2/disputes/{dispute_id}/evidence-files.
  • CreateDisputeEvidenceText. The URL is changed from /v2/disputes/{dispute_id}/evidence_text to /v2/disputes/{dispute_id}/evidence-text.
  • ListDisputeEvidence. The endpoint now returns a pagination cursor and accepts a pagination cursor in requests.
  • DISPUTES_READ and DISPUTES_WRITE permissions are required for all Disputes API endpoints instead of PAYMENTS_READ and PAYMENTS_WRITE.
  • DisputeEvidence. The evidence_id field is deprecated and replaced by the id field.
  • The dispute.state.changed webhook is renamed to dispute.state.updated.
  • Dispute object. The following breaking changes are made:
    • The dispute_id field is deprecated and replaced by the id field.
    • The reported_date field is deprecated and replaced by the reported_at field.
    • The evidence_ids field is deprecated with no replacement.

  For more information about the GA release of the Disputes API, see Disputes Overview.

• Inventory API:

  • CatalogStockConversion (Beta). Enables selling a product in multiple measurement units and lets Square sellers manage inventory counts of the product's stockable and a non-stockable variations in a self-consistent manner. For more information, see Enable Stock Conversion.

• Invoices API:

  • CreateInvoice. The location_id field is now optional and defaults to the location ID of the associated order. If specified in the request, the value must match the location ID of the associated order. This is a service-level change that applies to all Square API versions.

• Loyalty API:

  • LoyaltyProgramAccrualRule object. New excluded_category_ids and excluded_item_variation_ids fields that represent any categories and items that are excluded from accruing points in spend-based loyalty programs.

• Subscriptions API:

  • Subscription. The paid_until_date field is renamed to charge_through_date.

  • UpdateSubscription. The version field is now optional because it can update only the latest version of a subscription.

  • CreateSubscription. The idempotency_key field is now optional in the request. If you do not provide it, each CreateSubscription assumes a unique (never used before) value and creates a subscription for each call.

Documentation updates

• Order fee structure. Documented the transaction fee related to using the Orders API with a non-Square paymen