@lap v0.3 # Machine-readable API spec. Each @endpoint block is one API call. @api Square @base https://connect.squareup.com @version 2.0 @auth OAuth2 | ApiKey Authorization in header @endpoints 327 @hint download_for_search @toc mobile(1), oauth2(3), {location_id}(3), apple-pay(1), bank-accounts(3), bookings(24), cards(4), cash-drawers(3), catalog(14), channels(3), customers(31), devices(5), disputes(9), employees(2), events(4), gift-cards(9), inventory(13), invoices(10), labor(27), locations(20), loyalty(18), merchants(13), online-checkout(9), orders(19), payments(7), payouts(3), refunds(3), sites(4), subscriptions(12), team-members(12), terminals(15), transfer-orders(8), vendors(7), webhooks(8) @group mobile @endpoint POST /mobile/authorization-code @desc CreateMobileAuthorizationCode @optional {location_id: str # The Square location ID that the authorization code should be tied to.} @returns(200) {authorization_code: str, expires_at: str, errors: [map]} # Success @endgroup @group oauth2 @endpoint POST /oauth2/revoke @desc RevokeToken @optional {client_id: str # The Square-issued ID for your application, which is available on the **OAuth** page in the [Developer Dashboard](https://developer.squareup.com/apps)., access_token: str # The access token of the merchant whose token you want to revoke. Do not provide a value for `merchant_id` if you provide this parameter., merchant_id: str # The ID of the merchant whose token you want to revoke. Do not provide a value for `access_token` if you provide this parameter., revoke_only_access_token: bool # If `true`, terminate the given single access token, but do not terminate the entire authorization. Default: `false`} @returns(200) {success: bool, errors: [map]} # Success @endpoint POST /oauth2/token @desc ObtainToken @required {client_id: str # The Square-issued ID of your application, which is available as the **Application ID** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow and PKCE flow for any grant type., grant_type: str # The method used to obtain an OAuth access token. The request must include the credential that corresponds to the specified grant type. Valid values are: - `authorization_code` - Requires the `code` field. - `refresh_token` - Requires the `refresh_token` field. - `migration_token` - LEGACY for access tokens obtained using a Square API version prior to 2019-03-13. Requires the `migration_token` field.} @optional {client_secret: str # The secret key for your application, which is available as the **Application secret** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow for any grant type. Don't confuse your client secret with your personal access token., code: str # The authorization code to exchange for an OAuth access token. This is the `code` value that Square sent to your redirect URL in the authorization response. Required for the code flow and PKCE flow if `grant_type` is `authorization_code`., redirect_uri: str # The redirect URL for your application, which you registered as the **Redirect URL** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow and PKCE flow if `grant_type` is `authorization_code` and you provided the `redirect_uri` parameter in your authorization URL., refresh_token: str # A valid refresh token used to generate a new OAuth access token. This is a refresh token that was returned in a previous `ObtainToken` response. Required for the code flow and PKCE flow if `grant_type` is `refresh_token`., migration_token: str # __LEGACY__ A valid access token (obtained using a Square API version prior to 2019-03-13) used to generate a new OAuth access token. Required if `grant_type` is `migration_token`. For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens)., scopes: [str] # The list of permissions that are explicitly requested for the access token. For example, ["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]. The returned access token is limited to the permissions that are the intersection of these requested permissions and those authorized by the provided `refresh_token`. Optional for the code flow and PKCE flow if `grant_type` is `refresh_token`., short_lived: bool # Indicates whether the returned access token should expire in 24 hours. Optional for the code flow and PKCE flow for any grant type. The default value is `false`., code_verifier: str # The secret your application generated for the authorization request used to obtain the authorization code. This is the source of the `code_challenge` hash you provided in your authorization URL. Required for the PKCE flow if `grant_type` is `authorization_code`.} @returns(200) {access_token: str, token_type: str, expires_at: str, merchant_id: str, subscription_id: str, plan_id: str, id_token: str, refresh_token: str, short_lived: bool, errors: [map], refresh_token_expires_at: str} # Success @endpoint POST /oauth2/token/status @desc RetrieveTokenStatus @returns(200) {scopes: [str], expires_at: str, client_id: str, merchant_id: str, errors: [map]} # Success @endgroup @group {location_id} @endpoint GET /v1/{location_id}/orders @desc V1ListOrders @required {location_id: str # The ID of the location to list online store orders for.} @optional {order: str # The order in which payments are listed in the response., limit: int # The maximum number of payments to return in a single response. This value cannot exceed 200., batch_token: str # A pagination cursor to retrieve the next set of results for your original query to the endpoint.} @returns(200) Success @endpoint GET /v1/{location_id}/orders/{order_id} @desc V1RetrieveOrder @required {location_id: str # The ID of the order's associated location., order_id: str # The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint} @returns(200) {errors: [map]?, id: str, buyer_email: str?, recipient_name: str?, recipient_phone_number: str?, state: str, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, subtotal_money: map{amount: int?, currency_code: str}, total_shipping_money: map{amount: int?, currency_code: str}, total_tax_money: map{amount: int?, currency_code: str}, total_price_money: map{amount: int?, currency_code: str}, total_discount_money: map{amount: int?, currency_code: str}, created_at: str, updated_at: str, expires_at: str?, payment_id: str?, buyer_note: str?, completed_note: str?, refunded_note: str?, canceled_note: str?, tender: map{id: str, type: str, name: str?, employee_id: str?, receipt_url: str?, card_brand: str, pan_suffix: str?, entry_method: str, payment_note: str?, total_money: map{amount: int?, currency_code: str}, tendered_money: map{amount: int?, currency_code: str}, tendered_at: str?, settled_at: str?, change_back_money: map{amount: int?, currency_code: str}, refunded_money: map{amount: int?, currency_code: str}, is_exchange: bool?}, order_history: [map]?, promo_code: str?, btc_receive_address: str?, btc_price_satoshi: num?} # Success @endpoint PUT /v1/{location_id}/orders/{order_id} @desc V1UpdateOrder @required {location_id: str # The ID of the order's associated location., order_id: str # The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint, action: str(COMPLETE/CANCEL/REFUND)} @optional {shipped_tracking_number: str # The tracking number of the shipment associated with the order. Only valid if action is COMPLETE., completed_note: str # A merchant-specified note about the completion of the order. Only valid if action is COMPLETE., refunded_note: str # A merchant-specified note about the refunding of the order. Only valid if action is REFUND., canceled_note: str # A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.} @returns(200) {errors: [map]?, id: str, buyer_email: str?, recipient_name: str?, recipient_phone_number: str?, state: str, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, subtotal_money: map{amount: int?, currency_code: str}, total_shipping_money: map{amount: int?, currency_code: str}, total_tax_money: map{amount: int?, currency_code: str}, total_price_money: map{amount: int?, currency_code: str}, total_discount_money: map{amount: int?, currency_code: str}, created_at: str, updated_at: str, expires_at: str?, payment_id: str?, buyer_note: str?, completed_note: str?, refunded_note: str?, canceled_note: str?, tender: map{id: str, type: str, name: str?, employee_id: str?, receipt_url: str?, card_brand: str, pan_suffix: str?, entry_method: str, payment_note: str?, total_money: map{amount: int?, currency_code: str}, tendered_money: map{amount: int?, currency_code: str}, tendered_at: str?, settled_at: str?, change_back_money: map{amount: int?, currency_code: str}, refunded_money: map{amount: int?, currency_code: str}, is_exchange: bool?}, order_history: [map]?, promo_code: str?, btc_receive_address: str?, btc_price_satoshi: num?} # Success @endgroup @group apple-pay @endpoint POST /v2/apple-pay/domains @desc RegisterDomain @required {domain_name: str # A domain name as described in RFC-1034 that will be registered with ApplePay.} @returns(200) {errors: [map], status: str} # Success @endgroup @group bank-accounts @endpoint GET /v2/bank-accounts @desc ListBankAccounts @optional {cursor: str # The pagination cursor returned by a previous call to this endpoint. Use it in the next `ListBankAccounts` request to retrieve the next set of results. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information., limit: int # Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit., location_id: str # Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location.} @returns(200) {errors: [map], bank_accounts: [map], cursor: str} # Success @endpoint GET /v2/bank-accounts/by-v1-id/{v1_bank_account_id} @desc GetBankAccountByV1Id @required {v1_bank_account_id: str # Connect V1 ID of the desired `BankAccount`. For more information, see [Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api).} @returns(200) {errors: [map], bank_account: map{id: str, account_number_suffix: str, country: str, currency: str, account_type: str, holder_name: str, primary_bank_identification_number: str, secondary_bank_identification_number: str?, debit_mandate_reference_id: str?, reference_id: str?, location_id: str?, status: str, creditable: bool, debitable: bool, fingerprint: str?, version: int, bank_name: str?}} # Success @endpoint GET /v2/bank-accounts/{bank_account_id} @desc GetBankAccount @required {bank_account_id: str # Square-issued ID of the desired `BankAccount`.} @returns(200) {errors: [map], bank_account: map{id: str, account_number_suffix: str, country: str, currency: str, account_type: str, holder_name: str, primary_bank_identification_number: str, secondary_bank_identification_number: str?, debit_mandate_reference_id: str?, reference_id: str?, location_id: str?, status: str, creditable: bool, debitable: bool, fingerprint: str?, version: int, bank_name: str?}} # Success @endgroup @group bookings @endpoint GET /v2/bookings @desc ListBookings @optional {limit: int # The maximum number of results per page to return in a paged response., cursor: str # The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results., customer_id: str # The [customer](entity:Customer) for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved., team_member_id: str # The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved., location_id: str # The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved., start_at_min: str # The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used., start_at_max: str # The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used.} @returns(200) {bookings: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/bookings @desc CreateBooking @required {booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str, location_id: str, customer_id: str, customer_note: str, seller_note: str, appointment_segments: [map], transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map, source: str, address: map} # Represents a booking as a time-bound service contract for a seller's staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments.} @optional {idempotency_key: str # A unique key to make this request an idempotent operation.} @returns(200) {booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str?, location_id: str?, customer_id: str?, customer_note: str?, seller_note: str?, appointment_segments: [map]?, transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map{creator_type: str, team_member_id: str, customer_id: str}, source: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, errors: [map]} # Success @endpoint POST /v2/bookings/availability/search @desc SearchAvailability @required {query: map{filter!: map} # The query used to search for buyer-accessible availabilities of bookings.} @returns(200) {availabilities: [map], errors: [map]} # Success @endpoint POST /v2/bookings/bulk-retrieve @desc BulkRetrieveBookings @required {booking_ids: [str] # A non-empty list of [Booking](entity:Booking) IDs specifying bookings to retrieve.} @returns(200) {bookings: map, errors: [map]} # Success @endpoint GET /v2/bookings/business-booking-profile @desc RetrieveBusinessBookingProfile @returns(200) {business_booking_profile: map{seller_id: str?, created_at: str, booking_enabled: bool?, customer_timezone_choice: str, booking_policy: str, allow_user_cancel: bool?, business_appointment_settings: map{location_types: [str]?, alignment_time: str, min_booking_lead_time_seconds: int?, max_booking_lead_time_seconds: int?, any_team_member_booking_enabled: bool?, multiple_service_booking_enabled: bool?, max_appointments_per_day_limit_type: str, max_appointments_per_day_limit: int?, cancellation_window_seconds: int?, cancellation_fee_money: map{amount: int(int64)?, currency: str}, cancellation_policy: str, cancellation_policy_text: str?, skip_booking_flow_staff_selection: bool?}, support_seller_level_writes: bool?}, errors: [map]} # Success @endpoint GET /v2/bookings/custom-attribute-definitions @desc ListBookingCustomAttributeDefinitions @optional {limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {custom_attribute_definitions: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/bookings/custom-attribute-definitions @desc CreateBookingCustomAttributeDefinition @required {custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/bookings/custom-attribute-definitions/{key} @desc DeleteBookingCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/bookings/custom-attribute-definitions/{key} @desc RetrieveBookingCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.} @optional {version: int # The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/bookings/custom-attribute-definitions/{key} @desc UpdateBookingCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to update., custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/bookings/custom-attributes/bulk-delete @desc BulkDeleteBookingCustomAttributes @required {values: map # A map containing 1 to 25 individual Delete requests. For each request, provide an arbitrary ID that is unique for this `BulkDeleteBookingCustomAttributes` request and the information needed to delete a custom attribute.} @returns(200) {values: map, errors: [map]} # Success @endpoint POST /v2/bookings/custom-attributes/bulk-upsert @desc BulkUpsertBookingCustomAttributes @required {values: map # A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this `BulkUpsertBookingCustomAttributes` request and the information needed to create or update a custom attribute.} @returns(200) {values: map, errors: [map]} # Success @endpoint GET /v2/bookings/location-booking-profiles @desc ListLocationBookingProfiles @optional {limit: int # The maximum number of results to return in a paged response., cursor: str # The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.} @returns(200) {location_booking_profiles: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/bookings/location-booking-profiles/{location_id} @desc RetrieveLocationBookingProfile @required {location_id: str # The ID of the location to retrieve the booking profile.} @returns(200) {location_booking_profile: map{location_id: str?, booking_site_url: str?, online_booking_enabled: bool?}, errors: [map]} # Success @endpoint GET /v2/bookings/team-member-booking-profiles @desc ListTeamMemberBookingProfiles @optional {bookable_only: bool=false # Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`)., limit: int # The maximum number of results to return in a paged response., cursor: str # The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results., location_id: str # Indicates whether to include only team members enabled at the given location in the returned result.} @returns(200) {team_member_booking_profiles: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/bookings/team-member-booking-profiles/bulk-retrieve @desc BulkRetrieveTeamMemberBookingProfiles @required {team_member_ids: [str] # A non-empty list of IDs of team members whose booking profiles you want to retrieve.} @returns(200) {team_member_booking_profiles: map, errors: [map]} # Success @endpoint GET /v2/bookings/team-member-booking-profiles/{team_member_id} @desc RetrieveTeamMemberBookingProfile @required {team_member_id: str # The ID of the team member to retrieve.} @returns(200) {team_member_booking_profile: map{team_member_id: str, description: str, display_name: str, is_bookable: bool?, profile_image_url: str}, errors: [map]} # Success @endpoint GET /v2/bookings/{booking_id} @desc RetrieveBooking @required {booking_id: str # The ID of the [Booking](entity:Booking) object representing the to-be-retrieved booking.} @returns(200) {booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str?, location_id: str?, customer_id: str?, customer_note: str?, seller_note: str?, appointment_segments: [map]?, transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map{creator_type: str, team_member_id: str, customer_id: str}, source: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, errors: [map]} # Success @endpoint PUT /v2/bookings/{booking_id} @desc UpdateBooking @required {booking_id: str # The ID of the [Booking](entity:Booking) object representing the to-be-updated booking., booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str, location_id: str, customer_id: str, customer_note: str, seller_note: str, appointment_segments: [map], transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map, source: str, address: map} # Represents a booking as a time-bound service contract for a seller's staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments.} @optional {idempotency_key: str # A unique key to make this request an idempotent operation.} @returns(200) {booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str?, location_id: str?, customer_id: str?, customer_note: str?, seller_note: str?, appointment_segments: [map]?, transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map{creator_type: str, team_member_id: str, customer_id: str}, source: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, errors: [map]} # Success @endpoint POST /v2/bookings/{booking_id}/cancel @desc CancelBooking @required {booking_id: str # The ID of the [Booking](entity:Booking) object representing the to-be-cancelled booking.} @optional {idempotency_key: str # A unique key to make this request an idempotent operation., booking_version: int # The revision number for the booking used for optimistic concurrency.} @returns(200) {booking: map{id: str, version: int, status: str, created_at: str, updated_at: str, start_at: str?, location_id: str?, customer_id: str?, customer_note: str?, seller_note: str?, appointment_segments: [map]?, transition_time_minutes: int, all_day: bool, location_type: str, creator_details: map{creator_type: str, team_member_id: str, customer_id: str}, source: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, errors: [map]} # Success @endpoint GET /v2/bookings/{booking_id}/custom-attributes @desc ListBookingCustomAttributes @required {booking_id: str # The ID of the target [booking](entity:Booking).} @optional {limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., with_definitions: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attributes: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/bookings/{booking_id}/custom-attributes/{key} @desc DeleteBookingCustomAttribute @required {booking_id: str # The ID of the target [booking](entity:Booking)., key: str # The key of the custom attribute to delete. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/bookings/{booking_id}/custom-attributes/{key} @desc RetrieveBookingCustomAttribute @required {booking_id: str # The ID of the target [booking](entity:Booking)., key: str # The key of the custom attribute to retrieve. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @optional {with_definition: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of the custom attribute. Set this parameter to `true` to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is `false`., version: int # The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/bookings/{booking_id}/custom-attributes/{key} @desc UpsertBookingCustomAttribute @required {booking_id: str # The ID of the target [booking](entity:Booking)., key: str # The key of the custom attribute to create or update. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key., custom_attribute: map{key: str, value: any, version: int, visibility: str, definition: map, updated_at: str, created_at: str} # A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endgroup @group cards @endpoint GET /v2/cards @desc ListCards @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., customer_id: str # Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned., include_disabled: bool=false # Includes disabled cards. By default, all enabled cards owned by the merchant are returned., reference_id: str # Limit results to cards associated with the reference_id supplied., sort_order: str # Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.} @returns(200) {errors: [map], cards: [map], cursor: str} # Success @endpoint POST /v2/cards @desc CreateCard @required {idempotency_key: str # A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., source_id: str # The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id., card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64), exp_year: int(int64), cardholder_name: str, billing_address: map, fingerprint: str, customer_id: str, merchant_id: str, reference_id: str, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool} # Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.} @optional {verification_token: str # An identifying token generated by [Payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. See the [SCA Overview](https://developer.squareup.com/docs/sca-overview).} @returns(200) {errors: [map], card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}} # Success @endpoint GET /v2/cards/{card_id} @desc RetrieveCard @required {card_id: str # Unique ID for the desired Card.} @returns(200) {errors: [map], card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}} # Success @endpoint POST /v2/cards/{card_id}/disable @desc DisableCard @required {card_id: str # Unique ID for the desired Card.} @returns(200) {errors: [map], card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}} # Success @endgroup @group cash-drawers @endpoint GET /v2/cash-drawers/shifts @desc ListCashDrawerShifts @required {location_id: str # The ID of the location to query for a list of cash drawer shifts.} @optional {sort_order: str # The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC, begin_time: str # The inclusive start time of the query on opened_at, in ISO 8601 format., end_time: str # The exclusive end date of the query on opened_at, in ISO 8601 format., limit: int # Number of cash drawer shift events in a page of results (200 by default, 1000 max)., cursor: str # Opaque cursor for fetching the next page of results.} @returns(200) {cursor: str, errors: [map], cash_drawer_shifts: [map]} # Success @endpoint GET /v2/cash-drawers/shifts/{shift_id} @desc RetrieveCashDrawerShift @required {location_id: str # The ID of the location to retrieve cash drawer shifts from., shift_id: str # The shift ID.} @returns(200) {cash_drawer_shift: map{id: str, state: str, opened_at: str?, ended_at: str?, closed_at: str?, description: str?, opened_cash_money: map{amount: int(int64)?, currency: str}, cash_payment_money: map{amount: int(int64)?, currency: str}, cash_refunds_money: map{amount: int(int64)?, currency: str}, cash_paid_in_money: map{amount: int(int64)?, currency: str}, cash_paid_out_money: map{amount: int(int64)?, currency: str}, expected_cash_money: map{amount: int(int64)?, currency: str}, closed_cash_money: map{amount: int(int64)?, currency: str}, device: map{id: str, name: str?}, created_at: str, updated_at: str, location_id: str, team_member_ids: [str], opening_team_member_id: str, ending_team_member_id: str, closing_team_member_id: str}, errors: [map]} # Success @endpoint GET /v2/cash-drawers/shifts/{shift_id}/events @desc ListCashDrawerShiftEvents @required {location_id: str # The ID of the location to list cash drawer shifts for., shift_id: str # The shift ID.} @optional {limit: int # Number of resources to be returned in a page of results (200 by default, 1000 max)., cursor: str # Opaque cursor for fetching the next page of results.} @returns(200) {cursor: str, errors: [map], cash_drawer_shift_events: [map]} # Success @endgroup @group catalog @endpoint POST /v2/catalog/batch-delete @desc BatchDeleteCatalogObjects @required {object_ids: [str] # The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariation.} @returns(200) {errors: [map], deleted_object_ids: [str], deleted_at: str} # Success @endpoint POST /v2/catalog/batch-retrieve @desc BatchRetrieveCatalogObjects @required {object_ids: [str] # The IDs of the CatalogObjects to be retrieved.} @optional {include_related_objects: bool # If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the `related_objects` field of the response. If the `objects` field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the `related_objects` field of the response. Default value: `false`, catalog_version: int(int64) # The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will be from the current version of the catalog., include_deleted_objects: bool # Indicates whether to include (`true`) or not (`false`) in the response deleted objects, namely, those with the `is_deleted` attribute set to `true`., include_category_path_to_root: bool # Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload.} @returns(200) {errors: [map], objects: [map], related_objects: [map]} # Success @endpoint POST /v2/catalog/batch-upsert @desc BatchUpsertCatalogObjects @required {idempotency_key: str # A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., batches: [map{objects!: [map]}] # A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request. For each object, its `updated_at` field is ignored and replaced with a current [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), and its `is_deleted` field must not be set to `true`. To modify an existing object, supply its ID. To create a new object, use an ID starting with `#`. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID `#ABC` and a CatalogItemVariation with its `item_id` attribute set to `#ABC` in order to associate the CatalogItemVariation with its parent CatalogItem. Any `#`-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs. Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.} @returns(200) {errors: [map], objects: [map], updated_at: str, id_mappings: [map]} # Success @endpoint POST /v2/catalog/images @desc CreateCatalogImage @returns(200) {errors: [map], image: map{type: str, id: str, updated_at: str, version: int(int64), is_deleted: bool?, custom_attribute_values: map?, catalog_v1_ids: [map]?, present_at_all_locations: bool?, present_at_location_ids: [str]?, absent_at_location_ids: [str]?, item_data: map{name: str?, description: str?, abbreviation: str?, label_color: str?, is_taxable: bool?, category_id: str?, tax_ids: [str]?, modifier_list_info: [map]?, variations: [map]?, product_type: str, skip_modifier_screen: bool?, item_options: [map]?, ecom_uri: str?, ecom_image_uris: [str]?, image_ids: [str]?, sort_name: str?, categories: [map]?, description_html: str?, description_plaintext: str, channels: [str]?, is_archived: bool?, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, food_and_beverage_details: map{calorie_count: int?, dietary_preferences: [map]?, ingredients: [map]?}, reporting_category: map{id: str, ordinal: int(int64)?}, is_alcoholic: bool?}, category_data: map{name: str?, image_ids: [str]?, category_type: str, parent_category: map{id: str, ordinal: int(int64)?}, is_top_level: bool?, channels: [str]?, availability_period_ids: [str]?, online_visibility: bool?, root_category: str, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, path_to_root: [map]?}, item_variation_data: map{item_id: str?, name: str?, sku: str?, upc: str?, ordinal: int, pricing_type: str, price_money: map{amount: int(int64)?, currency: str}, location_overrides: [map]?, track_inventory: bool?, inventory_alert_type: str, inventory_alert_threshold: int(int64)?, user_data: str?, service_duration: int(int64)?, available_for_booking: bool?, item_option_values: [map]?, measurement_unit_id: str?, sellable: bool?, stockable: bool?, image_ids: [str]?, team_member_ids: [str]?, stockable_conversion: map{stockable_item_variation_id: str, stockable_quantity: str, nonstockable_quantity: str}}, tax_data: map{name: str?, calculation_phase: str, inclusion_type: str, percentage: str?, applies_to_custom_amounts: bool?, enabled: bool?, applies_to_product_set_id: str?}, discount_data: map{name: str?, discount_type: str, percentage: str?, amount_money: map{amount: int(int64)?, currency: str}, pin_required: bool?, label_color: str?, modify_tax_basis: str, maximum_amount_money: map{amount: int(int64)?, currency: str}}, modifier_list_data: map{name: str?, ordinal: int?, selection_type: str, modifiers: [map]?, image_ids: [str]?, allow_quantities: bool?, is_conversational: bool?, modifier_type: str, max_length: int?, text_required: bool?, internal_name: str?, min_selected_modifiers: int(int64)?, max_selected_modifiers: int(int64)?, hidden_from_customer: bool?}, modifier_data: map{name: str?, price_money: map{amount: int(int64)?, currency: str}, on_by_default: bool?, ordinal: int?, modifier_list_id: str?, location_overrides: [map]?, image_id: str?, hidden_online: bool?}, time_period_data: map{event: str?}, product_set_data: map{name: str?, product_ids_any: [str]?, product_ids_all: [str]?, quantity_exact: int(int64)?, quantity_min: int(int64)?, quantity_max: int(int64)?, all_products: bool?}, pricing_rule_data: map{name: str?, time_period_ids: [str]?, discount_id: str?, match_products_id: str?, apply_products_id: str?, exclude_products_id: str?, valid_from_date: str?, valid_from_local_time: str?, valid_until_date: str?, valid_until_local_time: str?, exclude_strategy: str, minimum_order_subtotal_money: map{amount: int(int64)?, currency: str}, customer_group_ids_any: [str]?}, image_data: map{name: str?, url: str?, caption: str?, photo_studio_order_id: str?}, measurement_unit_data: map{measurement_unit: map{custom_unit: map, area_unit: str, length_unit: str, volume_unit: str, weight_unit: str, generic_unit: str, time_unit: str, type: str}, precision: int?}, subscription_plan_data: map{name: str, phases: [map]?, subscription_plan_variations: [map]?, eligible_item_ids: [str]?, eligible_category_ids: [str]?, all_items: bool?}, item_option_data: map{name: str?, display_name: str?, description: str?, show_colors: bool?, values: [map]?}, item_option_value_data: map{item_option_id: str?, name: str?, description: str?, color: str?, ordinal: int?}, custom_attribute_definition_data: map{type: str, name: str, description: str?, source_application: map{product: str, application_id: str?, name: str?}, allowed_object_types: [str], seller_visibility: str, app_visibility: str, string_config: map{enforce_uniqueness: bool?}, number_config: map{precision: int?}, selection_config: map{max_allowed_selections: int?, allowed_selections: [map]?}, custom_attribute_usage_count: int, key: str?}, quick_amounts_settings_data: map{option: str, eligible_for_auto_amounts: bool?, amounts: [map]?}, subscription_plan_variation_data: map{name: str, phases: [map], subscription_plan_id: str?, monthly_billing_anchor_date: int(int64)?, can_prorate: bool?, successor_plan_variation_id: str?}, availability_period_data: map{start_local_time: str?, end_local_time: str?, day_of_week: str}}} # Success @endpoint PUT /v2/catalog/images/{image_id} @desc UpdateCatalogImage @required {image_id: str # The ID of the `CatalogImage` object to update the encapsulated image file.} @returns(200) {errors: [map], image: map{type: str, id: str, updated_at: str, version: int(int64), is_deleted: bool?, custom_attribute_values: map?, catalog_v1_ids: [map]?, present_at_all_locations: bool?, present_at_location_ids: [str]?, absent_at_location_ids: [str]?, item_data: map{name: str?, description: str?, abbreviation: str?, label_color: str?, is_taxable: bool?, category_id: str?, tax_ids: [str]?, modifier_list_info: [map]?, variations: [map]?, product_type: str, skip_modifier_screen: bool?, item_options: [map]?, ecom_uri: str?, ecom_image_uris: [str]?, image_ids: [str]?, sort_name: str?, categories: [map]?, description_html: str?, description_plaintext: str, channels: [str]?, is_archived: bool?, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, food_and_beverage_details: map{calorie_count: int?, dietary_preferences: [map]?, ingredients: [map]?}, reporting_category: map{id: str, ordinal: int(int64)?}, is_alcoholic: bool?}, category_data: map{name: str?, image_ids: [str]?, category_type: str, parent_category: map{id: str, ordinal: int(int64)?}, is_top_level: bool?, channels: [str]?, availability_period_ids: [str]?, online_visibility: bool?, root_category: str, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, path_to_root: [map]?}, item_variation_data: map{item_id: str?, name: str?, sku: str?, upc: str?, ordinal: int, pricing_type: str, price_money: map{amount: int(int64)?, currency: str}, location_overrides: [map]?, track_inventory: bool?, inventory_alert_type: str, inventory_alert_threshold: int(int64)?, user_data: str?, service_duration: int(int64)?, available_for_booking: bool?, item_option_values: [map]?, measurement_unit_id: str?, sellable: bool?, stockable: bool?, image_ids: [str]?, team_member_ids: [str]?, stockable_conversion: map{stockable_item_variation_id: str, stockable_quantity: str, nonstockable_quantity: str}}, tax_data: map{name: str?, calculation_phase: str, inclusion_type: str, percentage: str?, applies_to_custom_amounts: bool?, enabled: bool?, applies_to_product_set_id: str?}, discount_data: map{name: str?, discount_type: str, percentage: str?, amount_money: map{amount: int(int64)?, currency: str}, pin_required: bool?, label_color: str?, modify_tax_basis: str, maximum_amount_money: map{amount: int(int64)?, currency: str}}, modifier_list_data: map{name: str?, ordinal: int?, selection_type: str, modifiers: [map]?, image_ids: [str]?, allow_quantities: bool?, is_conversational: bool?, modifier_type: str, max_length: int?, text_required: bool?, internal_name: str?, min_selected_modifiers: int(int64)?, max_selected_modifiers: int(int64)?, hidden_from_customer: bool?}, modifier_data: map{name: str?, price_money: map{amount: int(int64)?, currency: str}, on_by_default: bool?, ordinal: int?, modifier_list_id: str?, location_overrides: [map]?, image_id: str?, hidden_online: bool?}, time_period_data: map{event: str?}, product_set_data: map{name: str?, product_ids_any: [str]?, product_ids_all: [str]?, quantity_exact: int(int64)?, quantity_min: int(int64)?, quantity_max: int(int64)?, all_products: bool?}, pricing_rule_data: map{name: str?, time_period_ids: [str]?, discount_id: str?, match_products_id: str?, apply_products_id: str?, exclude_products_id: str?, valid_from_date: str?, valid_from_local_time: str?, valid_until_date: str?, valid_until_local_time: str?, exclude_strategy: str, minimum_order_subtotal_money: map{amount: int(int64)?, currency: str}, customer_group_ids_any: [str]?}, image_data: map{name: str?, url: str?, caption: str?, photo_studio_order_id: str?}, measurement_unit_data: map{measurement_unit: map{custom_unit: map, area_unit: str, length_unit: str, volume_unit: str, weight_unit: str, generic_unit: str, time_unit: str, type: str}, precision: int?}, subscription_plan_data: map{name: str, phases: [map]?, subscription_plan_variations: [map]?, eligible_item_ids: [str]?, eligible_category_ids: [str]?, all_items: bool?}, item_option_data: map{name: str?, display_name: str?, description: str?, show_colors: bool?, values: [map]?}, item_option_value_data: map{item_option_id: str?, name: str?, description: str?, color: str?, ordinal: int?}, custom_attribute_definition_data: map{type: str, name: str, description: str?, source_application: map{product: str, application_id: str?, name: str?}, allowed_object_types: [str], seller_visibility: str, app_visibility: str, string_config: map{enforce_uniqueness: bool?}, number_config: map{precision: int?}, selection_config: map{max_allowed_selections: int?, allowed_selections: [map]?}, custom_attribute_usage_count: int, key: str?}, quick_amounts_settings_data: map{option: str, eligible_for_auto_amounts: bool?, amounts: [map]?}, subscription_plan_variation_data: map{name: str, phases: [map], subscription_plan_id: str?, monthly_billing_anchor_date: int(int64)?, can_prorate: bool?, successor_plan_variation_id: str?}, availability_period_data: map{start_local_time: str?, end_local_time: str?, day_of_week: str}}} # Success @endpoint GET /v2/catalog/info @desc CatalogInfo @returns(200) {errors: [map], limits: map{batch_upsert_max_objects_per_batch: int?, batch_upsert_max_total_objects: int?, batch_retrieve_max_object_ids: int?, search_max_page_limit: int?, batch_delete_max_object_ids: int?, update_item_taxes_max_item_ids: int?, update_item_taxes_max_taxes_to_enable: int?, update_item_taxes_max_taxes_to_disable: int?, update_item_modifier_lists_max_item_ids: int?, update_item_modifier_lists_max_modifier_lists_to_enable: int?, update_item_modifier_lists_max_modifier_lists_to_disable: int?}, standard_unit_description_group: map{standard_unit_descriptions: [map]?, language_code: str?}} # Success @endpoint GET /v2/catalog/list @desc ListCatalog @optional {cursor: str # The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., types: str # An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the [CatalogObjectType](entity:CatalogObjectType) enum, for example, `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS., catalog_version: int(int64) # The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the [CatalogObject](entity:CatalogObject)s' `version` attribute. If not included, results will be from the current version of the catalog.} @returns(200) {errors: [map], cursor: str, objects: [map]} # Success @endpoint POST /v2/catalog/object @desc UpsertCatalogObject @required {idempotency_key: str # A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., object: map{type!: str, id!: str, updated_at: str, version: int(int64), is_deleted: bool, custom_attribute_values: map, catalog_v1_ids: [map], present_at_all_locations: bool, present_at_location_ids: [str], absent_at_location_ids: [str], item_data: map, category_data: map, item_variation_data: map, tax_data: map, discount_data: map, modifier_list_data: map, modifier_data: map, time_period_data: map, product_set_data: map, pricing_rule_data: map, image_data: map, measurement_unit_data: map, subscription_plan_data: map, item_option_data: map, item_option_value_data: map, custom_attribute_definition_data: map, quick_amounts_settings_data: map, subscription_plan_variation_data: map, availability_period_data: map} # The wrapper object for the catalog entries of a given object type. Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object. For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance. In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance. For a more detailed discussion of the Catalog data model, please see the [Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide.} @returns(200) {errors: [map], catalog_object: map{type: str, id: str, updated_at: str, version: int(int64), is_deleted: bool?, custom_attribute_values: map?, catalog_v1_ids: [map]?, present_at_all_locations: bool?, present_at_location_ids: [str]?, absent_at_location_ids: [str]?, item_data: map{name: str?, description: str?, abbreviation: str?, label_color: str?, is_taxable: bool?, category_id: str?, tax_ids: [str]?, modifier_list_info: [map]?, variations: [map]?, product_type: str, skip_modifier_screen: bool?, item_options: [map]?, ecom_uri: str?, ecom_image_uris: [str]?, image_ids: [str]?, sort_name: str?, categories: [map]?, description_html: str?, description_plaintext: str, channels: [str]?, is_archived: bool?, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, food_and_beverage_details: map{calorie_count: int?, dietary_preferences: [map]?, ingredients: [map]?}, reporting_category: map{id: str, ordinal: int(int64)?}, is_alcoholic: bool?}, category_data: map{name: str?, image_ids: [str]?, category_type: str, parent_category: map{id: str, ordinal: int(int64)?}, is_top_level: bool?, channels: [str]?, availability_period_ids: [str]?, online_visibility: bool?, root_category: str, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, path_to_root: [map]?}, item_variation_data: map{item_id: str?, name: str?, sku: str?, upc: str?, ordinal: int, pricing_type: str, price_money: map{amount: int(int64)?, currency: str}, location_overrides: [map]?, track_inventory: bool?, inventory_alert_type: str, inventory_alert_threshold: int(int64)?, user_data: str?, service_duration: int(int64)?, available_for_booking: bool?, item_option_values: [map]?, measurement_unit_id: str?, sellable: bool?, stockable: bool?, image_ids: [str]?, team_member_ids: [str]?, stockable_conversion: map{stockable_item_variation_id: str, stockable_quantity: str, nonstockable_quantity: str}}, tax_data: map{name: str?, calculation_phase: str, inclusion_type: str, percentage: str?, applies_to_custom_amounts: bool?, enabled: bool?, applies_to_product_set_id: str?}, discount_data: map{name: str?, discount_type: str, percentage: str?, amount_money: map{amount: int(int64)?, currency: str}, pin_required: bool?, label_color: str?, modify_tax_basis: str, maximum_amount_money: map{amount: int(int64)?, currency: str}}, modifier_list_data: map{name: str?, ordinal: int?, selection_type: str, modifiers: [map]?, image_ids: [str]?, allow_quantities: bool?, is_conversational: bool?, modifier_type: str, max_length: int?, text_required: bool?, internal_name: str?, min_selected_modifiers: int(int64)?, max_selected_modifiers: int(int64)?, hidden_from_customer: bool?}, modifier_data: map{name: str?, price_money: map{amount: int(int64)?, currency: str}, on_by_default: bool?, ordinal: int?, modifier_list_id: str?, location_overrides: [map]?, image_id: str?, hidden_online: bool?}, time_period_data: map{event: str?}, product_set_data: map{name: str?, product_ids_any: [str]?, product_ids_all: [str]?, quantity_exact: int(int64)?, quantity_min: int(int64)?, quantity_max: int(int64)?, all_products: bool?}, pricing_rule_data: map{name: str?, time_period_ids: [str]?, discount_id: str?, match_products_id: str?, apply_products_id: str?, exclude_products_id: str?, valid_from_date: str?, valid_from_local_time: str?, valid_until_date: str?, valid_until_local_time: str?, exclude_strategy: str, minimum_order_subtotal_money: map{amount: int(int64)?, currency: str}, customer_group_ids_any: [str]?}, image_data: map{name: str?, url: str?, caption: str?, photo_studio_order_id: str?}, measurement_unit_data: map{measurement_unit: map{custom_unit: map, area_unit: str, length_unit: str, volume_unit: str, weight_unit: str, generic_unit: str, time_unit: str, type: str}, precision: int?}, subscription_plan_data: map{name: str, phases: [map]?, subscription_plan_variations: [map]?, eligible_item_ids: [str]?, eligible_category_ids: [str]?, all_items: bool?}, item_option_data: map{name: str?, display_name: str?, description: str?, show_colors: bool?, values: [map]?}, item_option_value_data: map{item_option_id: str?, name: str?, description: str?, color: str?, ordinal: int?}, custom_attribute_definition_data: map{type: str, name: str, description: str?, source_application: map{product: str, application_id: str?, name: str?}, allowed_object_types: [str], seller_visibility: str, app_visibility: str, string_config: map{enforce_uniqueness: bool?}, number_config: map{precision: int?}, selection_config: map{max_allowed_selections: int?, allowed_selections: [map]?}, custom_attribute_usage_count: int, key: str?}, quick_amounts_settings_data: map{option: str, eligible_for_auto_amounts: bool?, amounts: [map]?}, subscription_plan_variation_data: map{name: str, phases: [map], subscription_plan_id: str?, monthly_billing_anchor_date: int(int64)?, can_prorate: bool?, successor_plan_variation_id: str?}, availability_period_data: map{start_local_time: str?, end_local_time: str?, day_of_week: str}}, id_mappings: [map]} # Success @endpoint DELETE /v2/catalog/object/{object_id} @desc DeleteCatalogObject @required {object_id: str # The ID of the catalog object to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a catalog item will delete its catalog item variations).} @returns(200) {errors: [map], deleted_object_ids: [str], deleted_at: str} # Success @endpoint GET /v2/catalog/object/{object_id} @desc RetrieveCatalogObject @required {object_id: str # The object ID of any type of catalog objects to be retrieved.} @optional {include_related_objects: bool=false # If `true`, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field of the response. These objects are put in the `related_objects` field. Setting this to `true` is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the `related_objects` field of the response. If the `objects` field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the `related_objects` field of the response. Default value: `false`, catalog_version: int(int64) # Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of [CatalogObject](entity:CatalogObject)s. If not included, results will be from the current version of the catalog., include_category_path_to_root: bool=false # Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload.} @returns(200) {errors: [map], object: map{type: str, id: str, updated_at: str, version: int(int64), is_deleted: bool?, custom_attribute_values: map?, catalog_v1_ids: [map]?, present_at_all_locations: bool?, present_at_location_ids: [str]?, absent_at_location_ids: [str]?, item_data: map{name: str?, description: str?, abbreviation: str?, label_color: str?, is_taxable: bool?, category_id: str?, tax_ids: [str]?, modifier_list_info: [map]?, variations: [map]?, product_type: str, skip_modifier_screen: bool?, item_options: [map]?, ecom_uri: str?, ecom_image_uris: [str]?, image_ids: [str]?, sort_name: str?, categories: [map]?, description_html: str?, description_plaintext: str, channels: [str]?, is_archived: bool?, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, food_and_beverage_details: map{calorie_count: int?, dietary_preferences: [map]?, ingredients: [map]?}, reporting_category: map{id: str, ordinal: int(int64)?}, is_alcoholic: bool?}, category_data: map{name: str?, image_ids: [str]?, category_type: str, parent_category: map{id: str, ordinal: int(int64)?}, is_top_level: bool?, channels: [str]?, availability_period_ids: [str]?, online_visibility: bool?, root_category: str, ecom_seo_data: map{page_title: str?, page_description: str?, permalink: str?}, path_to_root: [map]?}, item_variation_data: map{item_id: str?, name: str?, sku: str?, upc: str?, ordinal: int, pricing_type: str, price_money: map{amount: int(int64)?, currency: str}, location_overrides: [map]?, track_inventory: bool?, inventory_alert_type: str, inventory_alert_threshold: int(int64)?, user_data: str?, service_duration: int(int64)?, available_for_booking: bool?, item_option_values: [map]?, measurement_unit_id: str?, sellable: bool?, stockable: bool?, image_ids: [str]?, team_member_ids: [str]?, stockable_conversion: map{stockable_item_variation_id: str, stockable_quantity: str, nonstockable_quantity: str}}, tax_data: map{name: str?, calculation_phase: str, inclusion_type: str, percentage: str?, applies_to_custom_amounts: bool?, enabled: bool?, applies_to_product_set_id: str?}, discount_data: map{name: str?, discount_type: str, percentage: str?, amount_money: map{amount: int(int64)?, currency: str}, pin_required: bool?, label_color: str?, modify_tax_basis: str, maximum_amount_money: map{amount: int(int64)?, currency: str}}, modifier_list_data: map{name: str?, ordinal: int?, selection_type: str, modifiers: [map]?, image_ids: [str]?, allow_quantities: bool?, is_conversational: bool?, modifier_type: str, max_length: int?, text_required: bool?, internal_name: str?, min_selected_modifiers: int(int64)?, max_selected_modifiers: int(int64)?, hidden_from_customer: bool?}, modifier_data: map{name: str?, price_money: map{amount: int(int64)?, currency: str}, on_by_default: bool?, ordinal: int?, modifier_list_id: str?, location_overrides: [map]?, image_id: str?, hidden_online: bool?}, time_period_data: map{event: str?}, product_set_data: map{name: str?, product_ids_any: [str]?, product_ids_all: [str]?, quantity_exact: int(int64)?, quantity_min: int(int64)?, quantity_max: int(int64)?, all_products: bool?}, pricing_rule_data: map{name: str?, time_period_ids: [str]?, discount_id: str?, match_products_id: str?, apply_products_id: str?, exclude_products_id: str?, valid_from_date: str?, valid_from_local_time: str?, valid_until_date: str?, valid_until_local_time: str?, exclude_strategy: str, minimum_order_subtotal_money: map{amount: int(int64)?, currency: str}, customer_group_ids_any: [str]?}, image_data: map{name: str?, url: str?, caption: str?, photo_studio_order_id: str?}, measurement_unit_data: map{measurement_unit: map{custom_unit: map, area_unit: str, length_unit: str, volume_unit: str, weight_unit: str, generic_unit: str, time_unit: str, type: str}, precision: int?}, subscription_plan_data: map{name: str, phases: [map]?, subscription_plan_variations: [map]?, eligible_item_ids: [str]?, eligible_category_ids: [str]?, all_items: bool?}, item_option_data: map{name: str?, display_name: str?, description: str?, show_colors: bool?, values: [map]?}, item_option_value_data: map{item_option_id: str?, name: str?, description: str?, color: str?, ordinal: int?}, custom_attribute_definition_data: map{type: str, name: str, description: str?, source_application: map{product: str, application_id: str?, name: str?}, allowed_object_types: [str], seller_visibility: str, app_visibility: str, string_config: map{enforce_uniqueness: bool?}, number_config: map{precision: int?}, selection_config: map{max_allowed_selections: int?, allowed_selections: [map]?}, custom_attribute_usage_count: int, key: str?}, quick_amounts_settings_data: map{option: str, eligible_for_auto_amounts: bool?, amounts: [map]?}, subscription_plan_variation_data: map{name: str, phases: [map], subscription_plan_id: str?, monthly_billing_anchor_date: int(int64)?, can_prorate: bool?, successor_plan_variation_id: str?}, availability_period_data: map{start_local_time: str?, end_local_time: str?, day_of_week: str}}, related_objects: [map]} # Success @endpoint POST /v2/catalog/search @desc SearchCatalogObjects @optional {cursor: str # The pagination cursor returned in the previous response. Leave unset for an initial request. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., object_types: [str] # The desired set of object types to appear in the search results. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. Note that if you wish for the query to return objects belonging to nested types (i.e., COMPONENT, IMAGE, ITEM_OPTION_VAL, ITEM_VARIATION, or MODIFIER), you must explicitly include all the types of interest in this field., include_deleted_objects: bool # If `true`, deleted objects will be included in the results. Defaults to `false`. Deleted objects will have their `is_deleted` field set to `true`. If `include_deleted_objects` is `true`, then the `include_category_path_to_root` request parameter must be `false`. Both properties cannot be `true` at the same time., include_related_objects: bool # If `true`, the response will include additional objects that are related to the requested objects. Related objects are objects that are referenced by object ID by the objects in the response. This is helpful if the objects are being fetched for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example: If the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the `related_objects` field of the response. If the `objects` field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the `related_objects` field of the response. Default value: `false`, begin_time: str # Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), in RFC 3339 format, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive - objects with a timestamp equal to `begin_time` will not be included in the response., query: map{sorted_attribute_query: map, exact_query: map, set_query: map, prefix_query: map, range_query: map, text_query: map, items_for_tax_query: map, items_for_modifier_list_query: map, items_for_item_options_query: map, item_variations_for_item_option_values_query: map} # A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the `SearchCatalogObjects` endpoint. Although a query can have multiple filters, only certain query types can be combined per call to [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects). Any combination of the following types may be used together: - [exact_query](entity:CatalogQueryExact) - [prefix_query](entity:CatalogQueryPrefix) - [range_query](entity:CatalogQueryRange) - [sorted_attribute_query](entity:CatalogQuerySortedAttribute) - [text_query](entity:CatalogQueryText) All other query types cannot be combined with any others. When a query filter is based on an attribute, the attribute must be searchable. Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters. Searchable attribute and objects queryable by searchable attributes: - `name`: `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, `CatalogTax`, `CatalogDiscount`, `CatalogModifier`, `CatalogModifierList`, `CatalogItemOption`, `CatalogItemOptionValue` - `description`: `CatalogItem`, `CatalogItemOptionValue` - `abbreviation`: `CatalogItem` - `upc`: `CatalogItemVariation` - `sku`: `CatalogItemVariation` - `caption`: `CatalogImage` - `display_name`: `CatalogItemOption` For example, to search for [CatalogItem](entity:CatalogItem) objects by searchable attributes, you can use the `"name"`, `"description"`, or `"abbreviation"` attribute in an applicable query filter., limit: int # A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored., include_category_path_to_root: bool # Specifies whether or not to include the `path_to_root` list for each returned category instance. The `path_to_root` list consists of `CategoryPathToRootNode` objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the `path_to_root` list is empty and is not returned in the response payload. If `include_category_path_to_root` is `true`, then the `include_deleted_objects` request parameter must be `false`. Both properties cannot be `true` at the same time.} @returns(200) {errors: [map], cursor: str, objects: [map], related_objects: [map], latest_time: str} # Success @endpoint POST /v2/catalog/search-catalog-items @desc SearchCatalogItems @optional {text_filter: str # The text filter expression to return items or item variations containing specified text in the `name`, `description`, or `abbreviation` attribute value of an item, or in the `name`, `sku`, or `upc` attribute value of an item variation., category_ids: [str] # The category id query expression to return items containing the specified category IDs., stock_levels: [str] # The stock-level query expression to return item variations with the specified stock levels. See [SearchCatalogItemsRequestStockLevel](#type-searchcatalogitemsrequeststocklevel) for possible values, enabled_location_ids: [str] # The enabled-location query expression to return items and item variations having specified enabled locations., cursor: str # The pagination token, returned in the previous response, used to fetch the next batch of pending results., limit: int # The maximum number of results to return per page. The default value is 100., sort_order: str(DESC/ASC) # The order (e.g., chronological or alphabetical) in which results from a request are returned., product_types: [str] # The product types query expression to return items or item variations having the specified product types., custom_attribute_filters: [map{custom_attribute_definition_id: str, key: str, string_filter: str, number_filter: map, selection_uids_filter: [str], bool_filter: bool}] # The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint., archived_state: str(ARCHIVED_STATE_NOT_ARCHIVED/ARCHIVED_STATE_ARCHIVED/ARCHIVED_STATE_ALL) # Defines the values for the `archived_state` query expression used in [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) to return the archived, not archived or either type of catalog items.} @returns(200) {errors: [map], items: [map], cursor: str, matched_variation_ids: [str]} # Success @endpoint POST /v2/catalog/update-item-modifier-lists @desc UpdateItemModifierLists @required {item_ids: [str] # The IDs of the catalog items associated with the CatalogModifierList objects being updated.} @optional {modifier_lists_to_enable: [str] # The IDs of the CatalogModifierList objects to enable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified., modifier_lists_to_disable: [str] # The IDs of the CatalogModifierList objects to disable for the CatalogItem. At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified.} @returns(200) {errors: [map], updated_at: str} # Success @endpoint POST /v2/catalog/update-item-taxes @desc UpdateItemTaxes @required {item_ids: [str] # IDs for the CatalogItems associated with the CatalogTax objects being updated. No more than 1,000 IDs may be provided.} @optional {taxes_to_enable: [str] # IDs of the CatalogTax objects to enable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified., taxes_to_disable: [str] # IDs of the CatalogTax objects to disable. At least one of `taxes_to_enable` or `taxes_to_disable` must be specified.} @returns(200) {errors: [map], updated_at: str} # Success @endgroup @group channels @endpoint GET /v2/channels @desc ListChannels @optional {reference_type: str # Type of reference associated to channel, reference_id: str # id of reference associated to channel, status: str # Status of channel, cursor: str # Cursor to fetch the next result, limit: int # Maximum number of results to return. When not provided the returned results will be cap at 100 channels.} @returns(200) {errors: [map], channels: [map], cursor: str} # Success @endpoint POST /v2/channels/bulk-retrieve @desc BulkRetrieveChannels @required {channel_ids: [str]} @returns(200) {errors: [map], responses: map} # Success @endpoint GET /v2/channels/{channel_id} @desc RetrieveChannel @required {channel_id: str # A channel id} @returns(200) {errors: [map], channel: map{id: str, merchant_id: str, name: str?, version: int, reference: map{type: str, id: str}, status: str, created_at: str, updated_at: str}} # Success @endgroup @group customers @endpoint GET /v2/customers @desc ListCustomers @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., sort_field: str # Indicates how customers should be sorted. The default value is `DEFAULT`., sort_order: str # Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`., count: bool=false # Indicates whether to return the total count of customers in the `count` field of the response. The default value is `false`.} @returns(200) {errors: [map], customers: [map], cursor: str, count: int(int64)} # Success @endpoint POST /v2/customers @desc CreateCustomer @optional {idempotency_key: str # The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)., given_name: str # The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters., family_name: str # The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters., company_name: str # A business name associated with the customer profile. The maximum length for this value is 500 characters., nickname: str # A nickname for the customer profile. The maximum length for this value is 100 characters., email_address: str # The email address associated with the customer profile. The maximum length for this value is 254 characters., address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., phone_number: str # The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)., reference_id: str # An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters., note: str # A custom note associated with the customer profile., birthday: str # The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified., tax_ids: map{eu_vat: str} # Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).} @returns(200) {errors: [map], customer: map{id: str, created_at: str, updated_at: str, given_name: str?, family_name: str?, nickname: str?, company_name: str?, email_address: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str?, birthday: str?, reference_id: str?, note: str?, preferences: map{email_unsubscribed: bool?}, creation_source: str, group_ids: [str]?, segment_ids: [str]?, version: int(int64), tax_ids: map{eu_vat: str?}}} # Success @endpoint POST /v2/customers/bulk-create @desc BulkCreateCustomers @required {customers: map # A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }` key-value pairs. Each key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) that uniquely identifies the create request. Each value contains the customer data used to create the customer profile.} @returns(200) {responses: map, errors: [map]} # Success @endpoint POST /v2/customers/bulk-delete @desc BulkDeleteCustomers @required {customer_ids: [str] # The IDs of the [customer profiles](entity:Customer) to delete.} @returns(200) {responses: map, errors: [map]} # Success @endpoint POST /v2/customers/bulk-retrieve @desc BulkRetrieveCustomers @required {customer_ids: [str] # The IDs of the [customer profiles](entity:Customer) to retrieve.} @returns(200) {responses: map, errors: [map]} # Success @endpoint POST /v2/customers/bulk-update @desc BulkUpdateCustomers @required {customers: map # A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }` key-value pairs. Each key is the ID of the [customer profile](entity:Customer) to update. To update a customer profile that was created by merging existing profiles, provide the ID of the newly created profile. Each value contains the updated customer data. Only new or changed fields are required. To add or update a field, specify the new value. To remove a field, specify `null`.} @returns(200) {responses: map, errors: [map]} # Success @endpoint GET /v2/customers/custom-attribute-definitions @desc ListCustomerCustomAttributeDefinitions @optional {limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {custom_attribute_definitions: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/customers/custom-attribute-definitions @desc CreateCustomerCustomAttributeDefinition @required {custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/customers/custom-attribute-definitions/{key} @desc DeleteCustomerCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/customers/custom-attribute-definitions/{key} @desc RetrieveCustomerCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.} @optional {version: int # The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/customers/custom-attribute-definitions/{key} @desc UpdateCustomerCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to update., custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/customers/custom-attributes/bulk-upsert @desc BulkUpsertCustomerCustomAttributes @required {values: map # A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this `BulkUpsertCustomerCustomAttributes` request and the information needed to create or update a custom attribute.} @returns(200) {values: map, errors: [map]} # Success @endpoint GET /v2/customers/groups @desc ListCustomerGroups @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], groups: [map], cursor: str} # Success @endpoint POST /v2/customers/groups @desc CreateCustomerGroup @required {group: map{id: str, name!: str, created_at: str, updated_at: str} # Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.} @optional {idempotency_key: str # The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {errors: [map], group: map{id: str, name: str, created_at: str, updated_at: str}} # Success @endpoint DELETE /v2/customers/groups/{group_id} @desc DeleteCustomerGroup @required {group_id: str # The ID of the customer group to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/customers/groups/{group_id} @desc RetrieveCustomerGroup @required {group_id: str # The ID of the customer group to retrieve.} @returns(200) {errors: [map], group: map{id: str, name: str, created_at: str, updated_at: str}} # Success @endpoint PUT /v2/customers/groups/{group_id} @desc UpdateCustomerGroup @required {group_id: str # The ID of the customer group to update., group: map{id: str, name!: str, created_at: str, updated_at: str} # Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.} @returns(200) {errors: [map], group: map{id: str, name: str, created_at: str, updated_at: str}} # Success @endpoint POST /v2/customers/search @desc SearchCustomers @optional {cursor: str # Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int(int64) # The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., query: map{filter: map, sort: map} # Represents filtering and sorting criteria for a [SearchCustomers](api-endpoint:Customers-SearchCustomers) request., count: bool # Indicates whether to return the total count of matching customers in the `count` field of the response. The default value is `false`.} @returns(200) {errors: [map], customers: [map], cursor: str, count: int(int64)} # Success @endpoint GET /v2/customers/segments @desc ListCustomerSegments @optional {cursor: str # A pagination cursor returned by previous calls to `ListCustomerSegments`. This cursor is used to retrieve the next set of query results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], segments: [map], cursor: str} # Success @endpoint GET /v2/customers/segments/{segment_id} @desc RetrieveCustomerSegment @required {segment_id: str # The Square-issued ID of the customer segment.} @returns(200) {errors: [map], segment: map{id: str, name: str, created_at: str, updated_at: str}} # Success @endpoint DELETE /v2/customers/{customer_id} @desc DeleteCustomer @required {customer_id: str # The ID of the customer to delete.} @optional {version: int(int64) # The current version of the customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).} @returns(200) {errors: [map]} # Success @endpoint GET /v2/customers/{customer_id} @desc RetrieveCustomer @required {customer_id: str # The ID of the customer to retrieve.} @returns(200) {errors: [map], customer: map{id: str, created_at: str, updated_at: str, given_name: str?, family_name: str?, nickname: str?, company_name: str?, email_address: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str?, birthday: str?, reference_id: str?, note: str?, preferences: map{email_unsubscribed: bool?}, creation_source: str, group_ids: [str]?, segment_ids: [str]?, version: int(int64), tax_ids: map{eu_vat: str?}}} # Success @endpoint PUT /v2/customers/{customer_id} @desc UpdateCustomer @required {customer_id: str # The ID of the customer to update.} @optional {given_name: str # The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters., family_name: str # The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters., company_name: str # A business name associated with the customer profile. The maximum length for this value is 500 characters., nickname: str # A nickname for the customer profile. The maximum length for this value is 100 characters., email_address: str # The email address associated with the customer profile. The maximum length for this value is 254 characters., address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., phone_number: str # The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)., reference_id: str # An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters., note: str # A custom note associated with the customer profile., birthday: str # The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified., version: int(int64) # The current version of the customer profile. As a best practice, you should include this field to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Update a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile)., tax_ids: map{eu_vat: str} # Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).} @returns(200) {errors: [map], customer: map{id: str, created_at: str, updated_at: str, given_name: str?, family_name: str?, nickname: str?, company_name: str?, email_address: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str?, birthday: str?, reference_id: str?, note: str?, preferences: map{email_unsubscribed: bool?}, creation_source: str, group_ids: [str]?, segment_ids: [str]?, version: int(int64), tax_ids: map{eu_vat: str?}}} # Success @endpoint POST /v2/customers/{customer_id}/cards @desc CreateCustomerCard @required {customer_id: str # The Square ID of the customer profile the card is linked to., card_nonce: str # A card nonce representing the credit card to link to the customer. Card nonces are generated by the Square payment form when customers enter their card information. For more information, see [Walkthrough: Integrate Square Payments in a Website](https://developer.squareup.com/docs/web-payments/take-card-payment). __NOTE:__ Card nonces generated by digital wallets (such as Apple Pay) cannot be used to create a customer card.} @optional {billing_address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., cardholder_name: str # The full name printed on the credit card., verification_token: str # An identifying token generated by [Payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.} @returns(200) {errors: [map], card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}} # Success @endpoint DELETE /v2/customers/{customer_id}/cards/{card_id} @desc DeleteCustomerCard @required {customer_id: str # The ID of the customer that the card on file belongs to., card_id: str # The ID of the card on file to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/customers/{customer_id}/custom-attributes @desc ListCustomerCustomAttributes @required {customer_id: str # The ID of the target [customer profile](entity:Customer).} @optional {limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., with_definitions: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attributes: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/customers/{customer_id}/custom-attributes/{key} @desc DeleteCustomerCustomAttribute @required {customer_id: str # The ID of the target [customer profile](entity:Customer)., key: str # The key of the custom attribute to delete. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/customers/{customer_id}/custom-attributes/{key} @desc RetrieveCustomerCustomAttribute @required {customer_id: str # The ID of the target [customer profile](entity:Customer)., key: str # The key of the custom attribute to retrieve. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @optional {with_definition: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of the custom attribute. Set this parameter to `true` to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is `false`., version: int # The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/customers/{customer_id}/custom-attributes/{key} @desc UpsertCustomerCustomAttribute @required {customer_id: str # The ID of the target [customer profile](entity:Customer)., key: str # The key of the custom attribute to create or update. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key., custom_attribute: map{key: str, value: any, version: int, visibility: str, definition: map, updated_at: str, created_at: str} # A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/customers/{customer_id}/groups/{group_id} @desc RemoveGroupFromCustomer @required {customer_id: str # The ID of the customer to remove from the group., group_id: str # The ID of the customer group to remove the customer from.} @returns(200) {errors: [map]} # Success @endpoint PUT /v2/customers/{customer_id}/groups/{group_id} @desc AddGroupToCustomer @required {customer_id: str # The ID of the customer to add to a group., group_id: str # The ID of the customer group to add the customer to.} @returns(200) {errors: [map]} # Success @endgroup @group devices @endpoint GET /v2/devices @desc ListDevices @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., sort_order: str # The order in which results are listed. - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)., limit: int # The number of results to return in a single page., location_id: str # If present, only returns devices at the target location.} @returns(200) {errors: [map], devices: [map], cursor: str} # Success @endpoint GET /v2/devices/codes @desc ListDeviceCodes @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information., location_id: str # If specified, only returns DeviceCodes of the specified location. Returns DeviceCodes of all locations if empty., product_type: str # If specified, only returns DeviceCodes targeting the specified product type. Returns DeviceCodes of all product types if empty., status: str # If specified, returns DeviceCodes with the specified statuses. Returns DeviceCodes of status `PAIRED` and `UNPAIRED` if empty.} @returns(200) {errors: [map], device_codes: [map], cursor: str} # Success @endpoint POST /v2/devices/codes @desc CreateDeviceCode @required {idempotency_key: str # A unique string that identifies this CreateDeviceCode request. Keys can be any valid string but must be unique for every CreateDeviceCode request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., device_code: map{id: str, name: str, code: str, device_id: str, product_type!: str, location_id: str, status: str, pair_by: str, created_at: str, status_changed_at: str, paired_at: str}} @returns(200) {errors: [map], device_code: map{id: str, name: str?, code: str, device_id: str, product_type: str, location_id: str?, status: str, pair_by: str, created_at: str, status_changed_at: str, paired_at: str}} # Success @endpoint GET /v2/devices/codes/{id} @desc GetDeviceCode @required {id: str # The unique identifier for the device code.} @returns(200) {errors: [map], device_code: map{id: str, name: str?, code: str, device_id: str, product_type: str, location_id: str?, status: str, pair_by: str, created_at: str, status_changed_at: str, paired_at: str}} # Success @endpoint GET /v2/devices/{device_id} @desc GetDevice @required {device_id: str # The unique ID for the desired `Device`.} @returns(200) {errors: [map], device: map{id: str, attributes: map{type: str, manufacturer: str, model: str?, name: str?, manufacturers_id: str?, updated_at: str, version: str, merchant_token: str?}, components: [map]?, status: map{category: str}}} # Success @endgroup @group disputes @endpoint GET /v2/disputes @desc ListDisputes @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., states: str # The dispute states used to filter the result. If not specified, the endpoint returns all disputes., location_id: str # The ID of the location for which to return a list of disputes. If not specified, the endpoint returns disputes associated with all locations.} @returns(200) {errors: [map], disputes: [map], cursor: str} # Success @endpoint GET /v2/disputes/{dispute_id} @desc RetrieveDispute @required {dispute_id: str # The ID of the dispute you want more details about.} @returns(200) {errors: [map], dispute: map{dispute_id: str?, id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, state: str, due_at: str?, disputed_payment: map{payment_id: str?}, evidence_ids: [str]?, card_brand: str, created_at: str, updated_at: str, brand_dispute_id: str?, reported_date: str?, reported_at: str?, version: int, location_id: str?}} # Success @endpoint POST /v2/disputes/{dispute_id}/accept @desc AcceptDispute @required {dispute_id: str # The ID of the dispute you want to accept.} @returns(200) {errors: [map], dispute: map{dispute_id: str?, id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, state: str, due_at: str?, disputed_payment: map{payment_id: str?}, evidence_ids: [str]?, card_brand: str, created_at: str, updated_at: str, brand_dispute_id: str?, reported_date: str?, reported_at: str?, version: int, location_id: str?}} # Success @endpoint GET /v2/disputes/{dispute_id}/evidence @desc ListDisputeEvidence @required {dispute_id: str # The ID of the dispute.} @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {evidence: [map], errors: [map], cursor: str} # Success @endpoint POST /v2/disputes/{dispute_id}/evidence-files @desc CreateDisputeEvidenceFile @required {dispute_id: str # The ID of the dispute for which you want to upload evidence.} @returns(200) {errors: [map], evidence: map{evidence_id: str?, id: str, dispute_id: str?, evidence_file: map{filename: str?, filetype: str?}, evidence_text: str?, uploaded_at: str?, evidence_type: str}} # Success @endpoint POST /v2/disputes/{dispute_id}/evidence-text @desc CreateDisputeEvidenceText @required {dispute_id: str # The ID of the dispute for which you want to upload evidence., idempotency_key: str # A unique key identifying the request. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)., evidence_text: str # The evidence string.} @optional {evidence_type: str(GENERIC_EVIDENCE/ONLINE_OR_APP_ACCESS_LOG/AUTHORIZATION_DOCUMENTATION/CANCELLATION_OR_REFUND_DOCUMENTATION/CARDHOLDER_COMMUNICATION/CARDHOLDER_INFORMATION/PURCHASE_ACKNOWLEDGEMENT/DUPLICATE_CHARGE_DOCUMENTATION/PRODUCT_OR_SERVICE_DESCRIPTION/RECEIPT/SERVICE_RECEIVED_DOCUMENTATION/PROOF_OF_DELIVERY_DOCUMENTATION/RELATED_TRANSACTION_DOCUMENTATION/REBUTTAL_EXPLANATION/TRACKING_NUMBER) # The type of the dispute evidence.} @returns(200) {errors: [map], evidence: map{evidence_id: str?, id: str, dispute_id: str?, evidence_file: map{filename: str?, filetype: str?}, evidence_text: str?, uploaded_at: str?, evidence_type: str}} # Success @endpoint DELETE /v2/disputes/{dispute_id}/evidence/{evidence_id} @desc DeleteDisputeEvidence @required {dispute_id: str # The ID of the dispute from which you want to remove evidence., evidence_id: str # The ID of the evidence you want to remove.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/disputes/{dispute_id}/evidence/{evidence_id} @desc RetrieveDisputeEvidence @required {dispute_id: str # The ID of the dispute from which you want to retrieve evidence metadata., evidence_id: str # The ID of the evidence to retrieve.} @returns(200) {errors: [map], evidence: map{evidence_id: str?, id: str, dispute_id: str?, evidence_file: map{filename: str?, filetype: str?}, evidence_text: str?, uploaded_at: str?, evidence_type: str}} # Success @endpoint POST /v2/disputes/{dispute_id}/submit-evidence @desc SubmitEvidence @required {dispute_id: str # The ID of the dispute for which you want to submit evidence.} @returns(200) {errors: [map], dispute: map{dispute_id: str?, id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, state: str, due_at: str?, disputed_payment: map{payment_id: str?}, evidence_ids: [str]?, card_brand: str, created_at: str, updated_at: str, brand_dispute_id: str?, reported_date: str?, reported_at: str?, version: int, location_id: str?}} # Success @endgroup @group employees @endpoint GET /v2/employees @desc ListEmployees @optional {location_id: str, status: str # Specifies the EmployeeStatus to filter the employee by., limit: int # The number of employees to be returned on each page., cursor: str # The token required to retrieve the specified page of results.} @returns(200) {employees: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/employees/{id} @desc RetrieveEmployee @required {id: str # UUID for the employee that was requested.} @returns(200) {employee: map{id: str, first_name: str?, last_name: str?, email: str?, phone_number: str?, location_ids: [str]?, status: str, is_owner: bool?, created_at: str, updated_at: str}, errors: [map]} # Success @endgroup @group events @endpoint POST /v2/events @desc SearchEvents @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of events for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). Default: 100, query: map{filter: map, sort: map} # Contains query criteria for the search.} @returns(200) {errors: [map], events: [map], metadata: [map], cursor: str} # Success @endpoint PUT /v2/events/disable @desc DisableEvents @returns(200) {errors: [map]} # Success @endpoint PUT /v2/events/enable @desc EnableEvents @returns(200) {errors: [map]} # Success @endpoint GET /v2/events/types @desc ListEventTypes @optional {api_version: str # The API version for which to list event types. Setting this field overrides the default version used by the application.} @returns(200) {errors: [map], event_types: [str], metadata: [map]} # Success @endgroup @group gift-cards @endpoint GET /v2/gift-cards @desc ListGiftCards @optional {type: str # If a [type](entity:GiftCardType) is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types., state: str # If a [state](entity:GiftCardStatus) is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states., limit: int # If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., customer_id: str # If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.} @returns(200) {errors: [map], gift_cards: [map], cursor: str} # Success @endpoint POST /v2/gift-cards @desc CreateGiftCard @required {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)., location_id: str # The ID of the [location](entity:Location) where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller's locations., gift_card: map{id: str, type!: str, gan_source: str, state: str, balance_money: map, gan: str, created_at: str, customer_ids: [str]} # Represents a Square gift card.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endpoint GET /v2/gift-cards/activities @desc ListGiftCardActivities @optional {gift_card_id: str # If a gift card ID is provided, the endpoint returns activities related to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller., type: str # If a [type](entity:GiftCardActivityType) is provided, the endpoint returns gift card activities of the specified type. Otherwise, the endpoint returns all types of gift card activities., location_id: str # If a location ID is provided, the endpoint returns gift card activities for the specified location. Otherwise, the endpoint returns gift card activities for all locations., begin_time: str # The timestamp for the beginning of the reporting period, in RFC 3339 format. This start time is inclusive. The default value is the current time minus one year., end_time: str # The timestamp for the end of the reporting period, in RFC 3339 format. This end time is inclusive. The default value is the current time., limit: int # If a limit is provided, the endpoint returns the specified number of results (or fewer) per page. The maximum value is 100. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., sort_order: str # The order in which the endpoint returns the activities, based on `created_at`. - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default).} @returns(200) {errors: [map], gift_card_activities: [map], cursor: str} # Success @endpoint POST /v2/gift-cards/activities @desc CreateGiftCardActivity @required {idempotency_key: str # A unique string that identifies the `CreateGiftCardActivity` request., gift_card_activity: map{id: str, type!: str, location_id!: str, created_at: str, gift_card_id: str, gift_card_gan: str, gift_card_balance_money: map, load_activity_details: map, activate_activity_details: map, redeem_activity_details: map, clear_balance_activity_details: map, deactivate_activity_details: map, adjust_increment_activity_details: map, adjust_decrement_activity_details: map, refund_activity_details: map, unlinked_activity_refund_activity_details: map, import_activity_details: map, block_activity_details: map, unblock_activity_details: map, import_reversal_activity_details: map, transfer_balance_to_activity_details: map, transfer_balance_from_activity_details: map} # Represents an action performed on a [gift card](entity:GiftCard) that affects its state or balance. A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity includes a `redeem_activity_details` field that contains information about the redemption.} @returns(200) {errors: [map], gift_card_activity: map{id: str, type: str, location_id: str, created_at: str, gift_card_id: str?, gift_card_gan: str?, gift_card_balance_money: map{amount: int(int64)?, currency: str}, load_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, order_id: str?, line_item_uid: str?, reference_id: str?, buyer_payment_instrument_ids: [str]?}, activate_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, order_id: str?, line_item_uid: str?, reference_id: str?, buyer_payment_instrument_ids: [str]?}, redeem_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, payment_id: str, reference_id: str?, status: str}, clear_balance_activity_details: map{reason: str}, deactivate_activity_details: map{reason: str}, adjust_increment_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, reason: str}, adjust_decrement_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, reason: str}, refund_activity_details: map{redeem_activity_id: str?, amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, payment_id: str}, unlinked_activity_refund_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, payment_id: str}, import_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}}, block_activity_details: map{reason: str}, unblock_activity_details: map{reason: str}, import_reversal_activity_details: map{amount_money: map{amount: int(int64)?, currency: str}}, transfer_balance_to_activity_details: map{transfer_from_gift_card_id: str, amount_money: map{amount: int(int64)?, currency: str}}, transfer_balance_from_activity_details: map{transfer_to_gift_card_id: str, amount_money: map{amount: int(int64)?, currency: str}}}} # Success @endpoint POST /v2/gift-cards/from-gan @desc RetrieveGiftCardFromGAN @required {gan: str # The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endpoint POST /v2/gift-cards/from-nonce @desc RetrieveGiftCardFromNonce @required {nonce: str # The payment token of the gift card to retrieve. Payment tokens are generated by the Web Payments SDK or In-App Payments SDK.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endpoint POST /v2/gift-cards/{gift_card_id}/link-customer @desc LinkCustomerToGiftCard @required {gift_card_id: str # The ID of the gift card to be linked., customer_id: str # The ID of the customer to link to the gift card.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endpoint POST /v2/gift-cards/{gift_card_id}/unlink-customer @desc UnlinkCustomerFromGiftCard @required {gift_card_id: str # The ID of the gift card to be unlinked., customer_id: str # The ID of the customer to unlink from the gift card.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endpoint GET /v2/gift-cards/{id} @desc RetrieveGiftCard @required {id: str # The ID of the gift card to retrieve.} @returns(200) {errors: [map], gift_card: map{id: str, type: str, gan_source: str, state: str, balance_money: map{amount: int(int64)?, currency: str}, gan: str?, created_at: str, customer_ids: [str]}} # Success @endgroup @group inventory @endpoint GET /v2/inventory/adjustment/{adjustment_id} @desc DeprecatedRetrieveInventoryAdjustment @required {adjustment_id: str # ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve.} @returns(200) {errors: [map], adjustment: map{id: str, reference_id: str?, from_state: str, to_state: str, location_id: str?, catalog_object_id: str?, catalog_object_type: str?, quantity: str?, total_price_money: map{amount: int(int64)?, currency: str}, occurred_at: str?, created_at: str, source: map{product: str, application_id: str?, name: str?}, employee_id: str?, team_member_id: str?, transaction_id: str, refund_id: str, purchase_order_id: str, goods_receipt_id: str, adjustment_group: map{id: str, root_adjustment_id: str, from_state: str, to_state: str}}} # Success @endpoint GET /v2/inventory/adjustments/{adjustment_id} @desc RetrieveInventoryAdjustment @required {adjustment_id: str # ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve.} @returns(200) {errors: [map], adjustment: map{id: str, reference_id: str?, from_state: str, to_state: str, location_id: str?, catalog_object_id: str?, catalog_object_type: str?, quantity: str?, total_price_money: map{amount: int(int64)?, currency: str}, occurred_at: str?, created_at: str, source: map{product: str, application_id: str?, name: str?}, employee_id: str?, team_member_id: str?, transaction_id: str, refund_id: str, purchase_order_id: str, goods_receipt_id: str, adjustment_group: map{id: str, root_adjustment_id: str, from_state: str, to_state: str}}} # Success @endpoint POST /v2/inventory/batch-change @desc DeprecatedBatchChangeInventory @required {idempotency_key: str # A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information.} @optional {changes: [map{type: str, physical_count: map, adjustment: map, transfer: map, measurement_unit: map, measurement_unit_id: str}] # The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order., ignore_unchanged_counts: bool # Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`.} @returns(200) {errors: [map], counts: [map], changes: [map]} # Success @endpoint POST /v2/inventory/batch-retrieve-changes @desc DeprecatedBatchRetrieveInventoryChanges @optional {catalog_object_ids: [str] # The filter to return results by `CatalogObject` ID. The filter is only applicable when set. The default value is null., location_ids: [str] # The filter to return results by `Location` ID. The filter is only applicable when set. The default value is null., types: [str] # The filter to return results by `InventoryChangeType` values other than `TRANSFER`. The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`., states: [str] # The filter to return `ADJUSTMENT` query results by `InventoryState`. This filter is only applied when set. The default value is null., updated_after: str # The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., updated_before: str # The filter to return results with their `created_at` or `calculated_at` value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information., limit: int # The number of [records](entity:InventoryChange) to return.} @returns(200) {errors: [map], changes: [map], cursor: str} # Success @endpoint POST /v2/inventory/batch-retrieve-counts @desc DeprecatedBatchRetrieveInventoryCounts @optional {catalog_object_ids: [str] # The filter to return results by `CatalogObject` ID. The filter is applicable only when set. The default is null., location_ids: [str] # The filter to return results by `Location` ID. This filter is applicable only when set. The default is null., updated_after: str # The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information., states: [str] # The filter to return results by `InventoryState`. The filter is only applicable when set. Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`. The default is null., limit: int # The number of [records](entity:InventoryCount) to return.} @returns(200) {errors: [map], counts: [map], cursor: str} # Success @endpoint POST /v2/inventory/changes/batch-create @desc BatchChangeInventory @required {idempotency_key: str # A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information.} @optional {changes: [map{type: str, physical_count: map, adjustment: map, transfer: map, measurement_unit: map, measurement_unit_id: str}] # The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order., ignore_unchanged_counts: bool # Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: `true`.} @returns(200) {errors: [map], counts: [map], changes: [map]} # Success @endpoint POST /v2/inventory/changes/batch-retrieve @desc BatchRetrieveInventoryChanges @optional {catalog_object_ids: [str] # The filter to return results by `CatalogObject` ID. The filter is only applicable when set. The default value is null., location_ids: [str] # The filter to return results by `Location` ID. The filter is only applicable when set. The default value is null., types: [str] # The filter to return results by `InventoryChangeType` values other than `TRANSFER`. The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`., states: [str] # The filter to return `ADJUSTMENT` query results by `InventoryState`. This filter is only applied when set. The default value is null., updated_after: str # The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., updated_before: str # The filter to return results with their `created_at` or `calculated_at` value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information., limit: int # The number of [records](entity:InventoryChange) to return.} @returns(200) {errors: [map], changes: [map], cursor: str} # Success @endpoint POST /v2/inventory/counts/batch-retrieve @desc BatchRetrieveInventoryCounts @optional {catalog_object_ids: [str] # The filter to return results by `CatalogObject` ID. The filter is applicable only when set. The default is null., location_ids: [str] # The filter to return results by `Location` ID. This filter is applicable only when set. The default is null., updated_after: str # The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information., states: [str] # The filter to return results by `InventoryState`. The filter is only applicable when set. Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`. The default is null., limit: int # The number of [records](entity:InventoryCount) to return.} @returns(200) {errors: [map], counts: [map], cursor: str} # Success @endpoint GET /v2/inventory/physical-count/{physical_count_id} @desc DeprecatedRetrieveInventoryPhysicalCount @required {physical_count_id: str # ID of the [InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve.} @returns(200) {errors: [map], count: map{id: str, reference_id: str?, catalog_object_id: str?, catalog_object_type: str?, state: str, location_id: str?, quantity: str?, source: map{product: str, application_id: str?, name: str?}, employee_id: str?, team_member_id: str?, occurred_at: str?, created_at: str}} # Success @endpoint GET /v2/inventory/physical-counts/{physical_count_id} @desc RetrieveInventoryPhysicalCount @required {physical_count_id: str # ID of the [InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve.} @returns(200) {errors: [map], count: map{id: str, reference_id: str?, catalog_object_id: str?, catalog_object_type: str?, state: str, location_id: str?, quantity: str?, source: map{product: str, application_id: str?, name: str?}, employee_id: str?, team_member_id: str?, occurred_at: str?, created_at: str}} # Success @endpoint GET /v2/inventory/transfers/{transfer_id} @desc RetrieveInventoryTransfer @required {transfer_id: str # ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve.} @returns(200) {errors: [map], transfer: map{id: str, reference_id: str?, state: str, from_location_id: str?, to_location_id: str?, catalog_object_id: str?, catalog_object_type: str?, quantity: str?, occurred_at: str?, created_at: str, source: map{product: str, application_id: str?, name: str?}, employee_id: str?, team_member_id: str?}} # Success @endpoint GET /v2/inventory/{catalog_object_id} @desc RetrieveInventoryCount @required {catalog_object_id: str # ID of the [CatalogObject](entity:CatalogObject) to retrieve.} @optional {location_ids: str # The [Location](entity:Location) IDs to look up as a comma-separated list. An empty list queries all locations., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.} @returns(200) {errors: [map], counts: [map], cursor: str} # Success @endpoint GET /v2/inventory/{catalog_object_id}/changes @desc RetrieveInventoryChanges @required {catalog_object_id: str # ID of the [CatalogObject](entity:CatalogObject) to retrieve.} @optional {location_ids: str # The [Location](entity:Location) IDs to look up as a comma-separated list. An empty list queries all locations., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.} @returns(200) {errors: [map], changes: [map], cursor: str} # Success @endgroup @group invoices @endpoint GET /v2/invoices @desc ListInvoices @required {location_id: str # The ID of the location for which to list invoices.} @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices.} @returns(200) {invoices: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/invoices @desc CreateInvoice @required {invoice: map{id: str, version: int, location_id: str, order_id: str, primary_recipient: map, payment_requests: [map], delivery_method: str, invoice_number: str, title: str, description: str, scheduled_at: str, public_url: str, next_payment_amount_money: map, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map, custom_fields: [map], subscription_id: str, sale_or_service_date: str, payment_conditions: str, store_payment_method_enabled: bool, attachments: [map], creator_team_member_id: str} # Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).} @optional {idempotency_key: str # A unique string that identifies the `CreateInvoice` request. If you do not provide `idempotency_key` (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {invoice: map{id: str, version: int, location_id: str?, order_id: str?, primary_recipient: map{customer_id: str?, given_name: str, family_name: str, email_address: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str, company_name: str, tax_ids: map{eu_vat: str}}, payment_requests: [map]?, delivery_method: str, invoice_number: str?, title: str?, description: str?, scheduled_at: str?, public_url: str, next_payment_amount_money: map{amount: int(int64)?, currency: str}, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map{card: bool?, square_gift_card: bool?, bank_account: bool?, buy_now_pay_later: bool?, cash_app_pay: bool?}, custom_fields: [map]?, subscription_id: str, sale_or_service_date: str?, payment_conditions: str?, store_payment_method_enabled: bool?, attachments: [map], creator_team_member_id: str}, errors: [map]} # Success @endpoint POST /v2/invoices/search @desc SearchInvoices @required {query: map{filter!: map, sort: map} # Describes query criteria for searching invoices.} @optional {limit: int # The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {invoices: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/invoices/{invoice_id} @desc DeleteInvoice @required {invoice_id: str # The ID of the invoice to delete.} @optional {version: int # The version of the [invoice](entity:Invoice) to delete. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices).} @returns(200) {errors: [map]} # Success @endpoint GET /v2/invoices/{invoice_id} @desc GetInvoice @required {invoice_id: str # The ID of the invoice to retrieve.} @returns(200) {invoice: map{id: str, version: int, location_id: str?, order_id: str?, primary_recipient: map{customer_id: str?, given_name: str, family_name: str, email_address: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str, company_name: str, tax_ids: map{eu_vat: str}}, payment_requests: [map]?, delivery_method: str, invoice_number: str?, title: str?, description: str?, scheduled_at: str?, public_url: str, next_payment_amount_money: map{amount: int(int64)?, currency: str}, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map{card: bool?, square_gift_card: bool?, bank_account: bool?, buy_now_pay_later: bool?, cash_app_pay: bool?}, custom_fields: [map]?, subscription_id: str, sale_or_service_date: str?, payment_conditions: str?, store_payment_method_enabled: bool?, attachments: [map], creator_team_member_id: str}, errors: [map]} # Success @endpoint PUT /v2/invoices/{invoice_id} @desc UpdateInvoice @required {invoice_id: str # The ID of the invoice to update., invoice: map{id: str, version: int, location_id: str, order_id: str, primary_recipient: map, payment_requests: [map], delivery_method: str, invoice_number: str, title: str, description: str, scheduled_at: str, public_url: str, next_payment_amount_money: map, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map, custom_fields: [map], subscription_id: str, sale_or_service_date: str, payment_conditions: str, store_payment_method_enabled: bool, attachments: [map], creator_team_member_id: str} # Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).} @optional {idempotency_key: str # A unique string that identifies the `UpdateInvoice` request. If you do not provide `idempotency_key` (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)., fields_to_clear: [str] # The list of fields to clear. Although this field is currently supported, we recommend using null values or the `remove` field when possible. For examples, see [Update an Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).} @returns(200) {invoice: map{id: str, version: int, location_id: str?, order_id: str?, primary_recipient: map{customer_id: str?, given_name: str, family_name: str, email_address: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str, company_name: str, tax_ids: map{eu_vat: str}}, payment_requests: [map]?, delivery_method: str, invoice_number: str?, title: str?, description: str?, scheduled_at: str?, public_url: str, next_payment_amount_money: map{amount: int(int64)?, currency: str}, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map{card: bool?, square_gift_card: bool?, bank_account: bool?, buy_now_pay_later: bool?, cash_app_pay: bool?}, custom_fields: [map]?, subscription_id: str, sale_or_service_date: str?, payment_conditions: str?, store_payment_method_enabled: bool?, attachments: [map], creator_team_member_id: str}, errors: [map]} # Success @endpoint POST /v2/invoices/{invoice_id}/attachments @desc CreateInvoiceAttachment @required {invoice_id: str # The ID of the [invoice](entity:Invoice) to attach the file to.} @returns(200) {attachment: map{id: str, filename: str, description: str, filesize: int, hash: str, mime_type: str, uploaded_at: str}, errors: [map]} # Success @endpoint DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id} @desc DeleteInvoiceAttachment @required {invoice_id: str # The ID of the [invoice](entity:Invoice) to delete the attachment from., attachment_id: str # The ID of the [attachment](entity:InvoiceAttachment) to delete.} @returns(200) {errors: [map]} # Success @endpoint POST /v2/invoices/{invoice_id}/cancel @desc CancelInvoice @required {invoice_id: str # The ID of the [invoice](entity:Invoice) to cancel., version: int # The version of the [invoice](entity:Invoice) to cancel. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices).} @returns(200) {invoice: map{id: str, version: int, location_id: str?, order_id: str?, primary_recipient: map{customer_id: str?, given_name: str, family_name: str, email_address: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str, company_name: str, tax_ids: map{eu_vat: str}}, payment_requests: [map]?, delivery_method: str, invoice_number: str?, title: str?, description: str?, scheduled_at: str?, public_url: str, next_payment_amount_money: map{amount: int(int64)?, currency: str}, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map{card: bool?, square_gift_card: bool?, bank_account: bool?, buy_now_pay_later: bool?, cash_app_pay: bool?}, custom_fields: [map]?, subscription_id: str, sale_or_service_date: str?, payment_conditions: str?, store_payment_method_enabled: bool?, attachments: [map], creator_team_member_id: str}, errors: [map]} # Success @endpoint POST /v2/invoices/{invoice_id}/publish @desc PublishInvoice @required {invoice_id: str # The ID of the invoice to publish., version: int # The version of the [invoice](entity:Invoice) to publish. This must match the current version of the invoice; otherwise, the request is rejected.} @optional {idempotency_key: str # A unique string that identifies the `PublishInvoice` request. If you do not provide `idempotency_key` (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {invoice: map{id: str, version: int, location_id: str?, order_id: str?, primary_recipient: map{customer_id: str?, given_name: str, family_name: str, email_address: str, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, phone_number: str, company_name: str, tax_ids: map{eu_vat: str}}, payment_requests: [map]?, delivery_method: str, invoice_number: str?, title: str?, description: str?, scheduled_at: str?, public_url: str, next_payment_amount_money: map{amount: int(int64)?, currency: str}, status: str, timezone: str, created_at: str, updated_at: str, accepted_payment_methods: map{card: bool?, square_gift_card: bool?, bank_account: bool?, buy_now_pay_later: bool?, cash_app_pay: bool?}, custom_fields: [map]?, subscription_id: str, sale_or_service_date: str?, payment_conditions: str?, store_payment_method_enabled: bool?, attachments: [map], creator_team_member_id: str}, errors: [map]} # Success @endgroup @group labor @endpoint GET /v2/labor/break-types @desc ListBreakTypes @optional {location_id: str # Filter the returned `BreakType` results to only those that are associated with the specified location., limit: int # The maximum number of `BreakType` results to return per page. The number can range between 1 and 200. The default is 200., cursor: str # A pointer to the next page of `BreakType` results to fetch.} @returns(200) {break_types: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/labor/break-types @desc CreateBreakType @required {break_type: map{id: str, location_id!: str, break_name!: str, expected_duration!: str, is_paid!: bool, version: int, created_at: str, updated_at: str} # A template for a type of [break](entity:Break) that can be added to a [timecard](entity:Timecard), including the expected duration and paid status.} @optional {idempotency_key: str # A unique string value to ensure the idempotency of the operation.} @returns(200) {break_type: map{id: str, location_id: str, break_name: str, expected_duration: str, is_paid: bool, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint DELETE /v2/labor/break-types/{id} @desc DeleteBreakType @required {id: str # The UUID for the `BreakType` being deleted.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/labor/break-types/{id} @desc GetBreakType @required {id: str # The UUID for the `BreakType` being retrieved.} @returns(200) {break_type: map{id: str, location_id: str, break_name: str, expected_duration: str, is_paid: bool, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint PUT /v2/labor/break-types/{id} @desc UpdateBreakType @required {id: str # The UUID for the `BreakType` being updated., break_type: map{id: str, location_id!: str, break_name!: str, expected_duration!: str, is_paid!: bool, version: int, created_at: str, updated_at: str} # A template for a type of [break](entity:Break) that can be added to a [timecard](entity:Timecard), including the expected duration and paid status.} @returns(200) {break_type: map{id: str, location_id: str, break_name: str, expected_duration: str, is_paid: bool, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint GET /v2/labor/employee-wages @desc ListEmployeeWages @optional {employee_id: str # Filter the returned wages to only those that are associated with the specified employee., limit: int # The maximum number of `EmployeeWage` results to return per page. The number can range between 1 and 200. The default is 200., cursor: str # A pointer to the next page of `EmployeeWage` results to fetch.} @returns(200) {employee_wages: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/labor/employee-wages/{id} @desc GetEmployeeWage @required {id: str # The UUID for the `EmployeeWage` being retrieved.} @returns(200) {employee_wage: map{id: str, employee_id: str?, title: str?, hourly_rate: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint POST /v2/labor/scheduled-shifts @desc CreateScheduledShift @required {scheduled_shift: map{id: str, draft_shift_details: map, published_shift_details: map, version: int, created_at: str, updated_at: str} # Represents a specific time slot in a work schedule. This object is used to manage the lifecycle of a scheduled shift from the draft to published state. A scheduled shift contains the latest draft shift details and current published shift details.} @optional {idempotency_key: str # A unique identifier for the `CreateScheduledShift` request, used to ensure the [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) of the operation.} @returns(200) {scheduled_shift: map{id: str, draft_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, published_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint POST /v2/labor/scheduled-shifts/bulk-publish @desc BulkPublishScheduledShifts @required {scheduled_shifts: map # A map of 1 to 100 key-value pairs that represent individual publish requests. - Each key is the ID of a scheduled shift you want to publish. - Each value is a `BulkPublishScheduledShiftsData` object that contains the `version` field or is an empty object.} @optional {scheduled_shift_notification_audience: str(ALL/AFFECTED/NONE) # Indicates whether Square sends an email notification to team members when a scheduled shift is published and which team members receive the notification.} @returns(200) {responses: map, errors: [map]} # Success @endpoint POST /v2/labor/scheduled-shifts/search @desc SearchScheduledShifts @optional {query: map{filter: map, sort: map} # Represents filter and sort criteria for the `query` field in a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request., limit: int # The maximum number of results to return in a single response page. The default value is 50., cursor: str # The pagination cursor returned by the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {scheduled_shifts: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/labor/scheduled-shifts/{id} @desc RetrieveScheduledShift @required {id: str # The ID of the scheduled shift to retrieve.} @returns(200) {scheduled_shift: map{id: str, draft_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, published_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint PUT /v2/labor/scheduled-shifts/{id} @desc UpdateScheduledShift @required {id: str # The ID of the scheduled shift to update., scheduled_shift: map{id: str, draft_shift_details: map, published_shift_details: map, version: int, created_at: str, updated_at: str} # Represents a specific time slot in a work schedule. This object is used to manage the lifecycle of a scheduled shift from the draft to published state. A scheduled shift contains the latest draft shift details and current published shift details.} @returns(200) {scheduled_shift: map{id: str, draft_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, published_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint POST /v2/labor/scheduled-shifts/{id}/publish @desc PublishScheduledShift @required {id: str # The ID of the scheduled shift to publish., idempotency_key: str # A unique identifier for the `PublishScheduledShift` request, used to ensure the [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) of the operation.} @optional {version: int # The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. If the provided version doesn't match the server version, the request fails. If omitted, Square executes a blind write, potentially overwriting data from another publish request., scheduled_shift_notification_audience: str(ALL/AFFECTED/NONE) # Indicates whether Square sends an email notification to team members when a scheduled shift is published and which team members receive the notification.} @returns(200) {scheduled_shift: map{id: str, draft_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, published_shift_details: map{team_member_id: str?, location_id: str?, job_id: str?, start_at: str?, end_at: str?, notes: str?, is_deleted: bool?, timezone: str}, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint POST /v2/labor/shifts @desc CreateShift @required {shift: map{id: str, employee_id: str, location_id!: str, timezone: str, start_at!: str, end_at: str, wage: map, breaks: [map], status: str, version: int, created_at: str, updated_at: str, team_member_id: str, declared_cash_tip_money: map} # A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift. Deprecated at Square API version 2025-05-21. Replaced by [Timecard](entity:Timecard). See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).} @optional {idempotency_key: str # A unique string value to ensure the idempotency of the operation.} @returns(200) {shift: map{id: str, employee_id: str?, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str?, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint POST /v2/labor/shifts/search @desc SearchShifts @optional {query: map{filter: map, sort: map} # The parameters of a `Shift` search query, which includes filter and sort options. Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes)., limit: int # The number of resources in a page (200 by default)., cursor: str # An opaque cursor for fetching the next page.} @returns(200) {shifts: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/labor/shifts/{id} @desc DeleteShift @required {id: str # The UUID for the `Shift` being deleted.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/labor/shifts/{id} @desc GetShift @required {id: str # The UUID for the `Shift` being retrieved.} @returns(200) {shift: map{id: str, employee_id: str?, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str?, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint PUT /v2/labor/shifts/{id} @desc UpdateShift @required {id: str # The ID of the object being updated., shift: map{id: str, employee_id: str, location_id!: str, timezone: str, start_at!: str, end_at: str, wage: map, breaks: [map], status: str, version: int, created_at: str, updated_at: str, team_member_id: str, declared_cash_tip_money: map} # A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift. Deprecated at Square API version 2025-05-21. Replaced by [Timecard](entity:Timecard). See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).} @returns(200) {shift: map{id: str, employee_id: str?, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str?, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint GET /v2/labor/team-member-wages @desc ListTeamMemberWages @optional {team_member_id: str # Filter the returned wages to only those that are associated with the specified team member., limit: int # The maximum number of `TeamMemberWage` results to return per page. The number can range between 1 and 200. The default is 200., cursor: str # A pointer to the next page of `EmployeeWage` results to fetch.} @returns(200) {team_member_wages: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/labor/team-member-wages/{id} @desc GetTeamMemberWage @required {id: str # The UUID for the `TeamMemberWage` being retrieved.} @returns(200) {team_member_wage: map{id: str, team_member_id: str?, title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str?, tip_eligible: bool?}, errors: [map]} # Success @endpoint POST /v2/labor/timecards @desc CreateTimecard @required {timecard: map{id: str, location_id!: str, timezone: str, start_at!: str, end_at: str, wage: map, breaks: [map], status: str, version: int, created_at: str, updated_at: str, team_member_id!: str, declared_cash_tip_money: map} # A record of the hourly rate, start time, and end time of a single timecard (shift) for a team member. This might include a record of the start and end times of breaks taken during the shift.} @optional {idempotency_key: str # A unique string value to ensure the idempotency of the operation.} @returns(200) {timecard: map{id: str, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint POST /v2/labor/timecards/search @desc SearchTimecards @optional {query: map{filter: map, sort: map} # The parameters of a `Timecard` search query, which includes filter and sort options., limit: int # The number of resources in a page (200 by default)., cursor: str # An opaque cursor for fetching the next page.} @returns(200) {timecards: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/labor/timecards/{id} @desc DeleteTimecard @required {id: str # The UUID for the `Timecard` being deleted.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/labor/timecards/{id} @desc RetrieveTimecard @required {id: str # The UUID for the `Timecard` being retrieved.} @returns(200) {timecard: map{id: str, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint PUT /v2/labor/timecards/{id} @desc UpdateTimecard @required {id: str # The ID of the object being updated., timecard: map{id: str, location_id!: str, timezone: str, start_at!: str, end_at: str, wage: map, breaks: [map], status: str, version: int, created_at: str, updated_at: str, team_member_id!: str, declared_cash_tip_money: map} # A record of the hourly rate, start time, and end time of a single timecard (shift) for a team member. This might include a record of the start and end times of breaks taken during the shift.} @returns(200) {timecard: map{id: str, location_id: str, timezone: str?, start_at: str, end_at: str?, wage: map{title: str?, hourly_rate: map{amount: int(int64)?, currency: str}, job_id: str, tip_eligible: bool?}, breaks: [map]?, status: str, version: int, created_at: str, updated_at: str, team_member_id: str, declared_cash_tip_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint GET /v2/labor/workweek-configs @desc ListWorkweekConfigs @optional {limit: int # The maximum number of `WorkweekConfigs` results to return per page., cursor: str # A pointer to the next page of `WorkweekConfig` results to fetch.} @returns(200) {workweek_configs: [map], cursor: str, errors: [map]} # Success @endpoint PUT /v2/labor/workweek-configs/{id} @desc UpdateWorkweekConfig @required {id: str # The UUID for the `WorkweekConfig` object being updated., workweek_config: map{id: str, start_of_week!: str, start_of_day_local_time!: str, version: int, created_at: str, updated_at: str} # Sets the day of the week and hour of the day that a business starts a workweek. This is used to calculate overtime pay.} @returns(200) {workweek_config: map{id: str, start_of_week: str, start_of_day_local_time: str, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endgroup @group locations @endpoint GET /v2/locations @desc ListLocations @returns(200) {errors: [map], locations: [map]} # Success @endpoint POST /v2/locations @desc CreateLocation @optional {location: map{id: str, name: str, address: map, timezone: str, capabilities: [str], status: str, created_at: str, merchant_id: str, country: str, language_code: str, currency: str, phone_number: str, business_name: str, type: str, website_url: str, business_hours: map, business_email: str, description: str, twitter_username: str, instagram_username: str, facebook_url: str, coordinates: map, logo_url: str, pos_background_url: str, mcc: str, full_format_logo_url: str, tax_ids: map} # Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api).} @returns(200) {errors: [map], location: map{id: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, timezone: str?, capabilities: [str], status: str, created_at: str, merchant_id: str, country: str, language_code: str?, currency: str, phone_number: str?, business_name: str?, type: str, website_url: str?, business_hours: map{periods: [map]?}, business_email: str?, description: str?, twitter_username: str?, instagram_username: str?, facebook_url: str?, coordinates: map{latitude: num?, longitude: num?}, logo_url: str, pos_background_url: str, mcc: str?, full_format_logo_url: str, tax_ids: map{eu_vat: str, fr_siret: str, fr_naf: str, es_nif: str, jp_qii: str}}} # Success @endpoint GET /v2/locations/custom-attribute-definitions @desc ListLocationCustomAttributeDefinitions @optional {visibility_filter: str # Filters the `CustomAttributeDefinition` results by their `visibility` values., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {custom_attribute_definitions: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/locations/custom-attribute-definitions @desc CreateLocationCustomAttributeDefinition @required {custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/locations/custom-attribute-definitions/{key} @desc DeleteLocationCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/locations/custom-attribute-definitions/{key} @desc RetrieveLocationCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.} @optional {version: int # The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/locations/custom-attribute-definitions/{key} @desc UpdateLocationCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to update., custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/locations/custom-attributes/bulk-delete @desc BulkDeleteLocationCustomAttributes @required {values: map # The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response.} @returns(200) {values: map, errors: [map]} # Success @endpoint POST /v2/locations/custom-attributes/bulk-upsert @desc BulkUpsertLocationCustomAttributes @required {values: map # A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this `BulkUpsertLocationCustomAttributes` request and the information needed to create or update a custom attribute.} @returns(200) {values: map, errors: [map]} # Success @endpoint GET /v2/locations/{location_id} @desc RetrieveLocation @required {location_id: str # The ID of the location to retrieve. Specify the string "main" to return the main location.} @returns(200) {errors: [map], location: map{id: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, timezone: str?, capabilities: [str], status: str, created_at: str, merchant_id: str, country: str, language_code: str?, currency: str, phone_number: str?, business_name: str?, type: str, website_url: str?, business_hours: map{periods: [map]?}, business_email: str?, description: str?, twitter_username: str?, instagram_username: str?, facebook_url: str?, coordinates: map{latitude: num?, longitude: num?}, logo_url: str, pos_background_url: str, mcc: str?, full_format_logo_url: str, tax_ids: map{eu_vat: str, fr_siret: str, fr_naf: str, es_nif: str, jp_qii: str}}} # Success @endpoint PUT /v2/locations/{location_id} @desc UpdateLocation @required {location_id: str # The ID of the location to update.} @optional {location: map{id: str, name: str, address: map, timezone: str, capabilities: [str], status: str, created_at: str, merchant_id: str, country: str, language_code: str, currency: str, phone_number: str, business_name: str, type: str, website_url: str, business_hours: map, business_email: str, description: str, twitter_username: str, instagram_username: str, facebook_url: str, coordinates: map, logo_url: str, pos_background_url: str, mcc: str, full_format_logo_url: str, tax_ids: map} # Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api).} @returns(200) {errors: [map], location: map{id: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, timezone: str?, capabilities: [str], status: str, created_at: str, merchant_id: str, country: str, language_code: str?, currency: str, phone_number: str?, business_name: str?, type: str, website_url: str?, business_hours: map{periods: [map]?}, business_email: str?, description: str?, twitter_username: str?, instagram_username: str?, facebook_url: str?, coordinates: map{latitude: num?, longitude: num?}, logo_url: str, pos_background_url: str, mcc: str?, full_format_logo_url: str, tax_ids: map{eu_vat: str, fr_siret: str, fr_naf: str, es_nif: str, jp_qii: str}}} # Success @endpoint POST /v2/locations/{location_id}/checkouts @desc CreateCheckout @required {location_id: str # The ID of the business location to associate the checkout with., idempotency_key: str # A unique string that identifies this checkout among others you have created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID. The idempotency key is used to avoid processing the same order more than once. If you are unsure whether a particular checkout was created successfully, you can attempt it again with the same idempotency key and all the same other parameters without worrying about creating duplicates. You should use a random number/string generator native to the language you are working in to generate strings for your idempotency keys. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)., order: map{order: map, idempotency_key: str}} @optional {ask_for_shipping_address: bool # If `true`, Square Checkout collects shipping information on your behalf and stores that information with the transaction information in the Square Seller Dashboard. Default: `false`., merchant_support_email: str # The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the seller. If this value is not set, the confirmation page and email display the primary email address associated with the seller's Square account. Default: none; only exists if explicitly set., pre_populate_buyer_email: str # If provided, the buyer's email is prepopulated on the checkout page as an editable text field. Default: none; only exists if explicitly set., pre_populate_shipping_address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., redirect_url: str # The URL to redirect to after the checkout is completed with `checkoutId`, `transactionId`, and `referenceId` appended as URL parameters. For example, if the provided redirect URL is `http://www.example.com/order-complete`, a successful transaction redirects the customer to: `http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx` If you do not provide a redirect URL, Square Checkout displays an order confirmation page on your behalf; however, it is strongly recommended that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow. Default: none; only exists if explicitly set., additional_recipients: [map{location_id!: str, description!: str, amount_money!: map}] # The basic primitive of a multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the `amount_money` value in your `additional_recipients` field cannot be more than 90% of the `total_money` calculated by Square for your order. The `location_id` must be a valid seller location where the checkout is occurring. This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission. This field is currently not supported in the Square Sandbox., note: str # An optional note to associate with the `checkout` object. This value cannot exceed 60 characters.} @returns(200) {checkout: map{id: str, checkout_page_url: str?, ask_for_shipping_address: bool?, merchant_support_email: str?, pre_populate_buyer_email: str?, pre_populate_shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, redirect_url: str?, order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map, tax_money: map, discount_money: map, tip_money: map, service_charge_money: map}, net_amounts: map{total_money: map, tax_money: map, discount_money: map, tip_money: map, service_charge_money: map}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, created_at: str, additional_recipients: [map]?}, errors: [map]} # Success @endpoint GET /v2/locations/{location_id}/custom-attributes @desc ListLocationCustomAttributes @required {location_id: str # The ID of the target [location](entity:Location).} @optional {visibility_filter: str # Filters the `CustomAttributeDefinition` results by their `visibility` values., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., with_definitions: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attributes: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/locations/{location_id}/custom-attributes/{key} @desc DeleteLocationCustomAttribute @required {location_id: str # The ID of the target [location](entity:Location)., key: str # The key of the custom attribute to delete. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/locations/{location_id}/custom-attributes/{key} @desc RetrieveLocationCustomAttribute @required {location_id: str # The ID of the target [location](entity:Location)., key: str # The key of the custom attribute to retrieve. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @optional {with_definition: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of the custom attribute. Set this parameter to `true` to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is `false`., version: int # The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/locations/{location_id}/custom-attributes/{key} @desc UpsertLocationCustomAttribute @required {location_id: str # The ID of the target [location](entity:Location)., key: str # The key of the custom attribute to create or update. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key., custom_attribute: map{key: str, value: any, version: int, visibility: str, definition: map, updated_at: str, created_at: str} # A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint GET /v2/locations/{location_id}/transactions @desc ListTransactions @required {location_id: str # The ID of the location to list transactions for.} @optional {begin_time: str # The beginning of the requested reporting period, in RFC 3339 format. See [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity. Default value: The current time minus one year., end_time: str # The end of the requested reporting period, in RFC 3339 format. See [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity. Default value: The current time., sort_order: str # The order in which results are listed in the response (`ASC` for oldest first, `DESC` for newest first). Default value: `DESC`, cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information.} @returns(200) {errors: [map], transactions: [map], cursor: str} # Success @endpoint GET /v2/locations/{location_id}/transactions/{transaction_id} @desc RetrieveTransaction @required {location_id: str # The ID of the transaction's associated location., transaction_id: str # The ID of the transaction to retrieve.} @returns(200) {errors: [map], transaction: map{id: str, location_id: str?, created_at: str, tenders: [map]?, refunds: [map]?, reference_id: str?, product: str, client_id: str?, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, order_id: str?}} # Success @endpoint POST /v2/locations/{location_id}/transactions/{transaction_id}/capture @desc CaptureTransaction @required {location_id: str, transaction_id: str} @returns(200) {errors: [map]} # Success @endpoint POST /v2/locations/{location_id}/transactions/{transaction_id}/void @desc VoidTransaction @required {location_id: str, transaction_id: str} @returns(200) {errors: [map]} # Success @endgroup @group loyalty @endpoint POST /v2/loyalty/accounts @desc CreateLoyaltyAccount @required {loyalty_account: map{id: str, program_id!: str, balance: int, lifetime_points: int, customer_id: str, enrolled_at: str, created_at: str, updated_at: str, mapping: map, expiring_point_deadlines: [map]} # Describes a loyalty account in a [loyalty program](entity:LoyaltyProgram). For more information, see [Create and Retrieve Loyalty Accounts](https://developer.squareup.com/docs/loyalty-api/loyalty-accounts)., idempotency_key: str # A unique string that identifies this `CreateLoyaltyAccount` request. Keys can be any valid string, but must be unique for every request.} @returns(200) {errors: [map], loyalty_account: map{id: str, program_id: str, balance: int, lifetime_points: int, customer_id: str?, enrolled_at: str?, created_at: str, updated_at: str, mapping: map{id: str, created_at: str, phone_number: str?}, expiring_point_deadlines: [map]?}} # Success @endpoint POST /v2/loyalty/accounts/search @desc SearchLoyaltyAccounts @optional {query: map{mappings: [map], customer_ids: [str]} # The search criteria for the loyalty accounts., limit: int # The maximum number of results to include in the response. The default value is 30., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], loyalty_accounts: [map], cursor: str} # Success @endpoint GET /v2/loyalty/accounts/{account_id} @desc RetrieveLoyaltyAccount @required {account_id: str # The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve.} @returns(200) {errors: [map], loyalty_account: map{id: str, program_id: str, balance: int, lifetime_points: int, customer_id: str?, enrolled_at: str?, created_at: str, updated_at: str, mapping: map{id: str, created_at: str, phone_number: str?}, expiring_point_deadlines: [map]?}} # Success @endpoint POST /v2/loyalty/accounts/{account_id}/accumulate @desc AccumulateLoyaltyPoints @required {account_id: str # The ID of the target [loyalty account](entity:LoyaltyAccount)., accumulate_points: map{loyalty_program_id: str, points: int, order_id: str} # Provides metadata when the event `type` is `ACCUMULATE_POINTS`., idempotency_key: str # A unique string that identifies the `AccumulateLoyaltyPoints` request. Keys can be any valid string but must be unique for every request., location_id: str # The [location](entity:Location) where the purchase was made.} @returns(200) {errors: [map], event: map{id: str, type: str, created_at: str, accumulate_points: map{loyalty_program_id: str, points: int?, order_id: str?}, create_reward: map{loyalty_program_id: str, reward_id: str, points: int}, redeem_reward: map{loyalty_program_id: str, reward_id: str, order_id: str}, delete_reward: map{loyalty_program_id: str, reward_id: str, points: int}, adjust_points: map{loyalty_program_id: str, points: int, reason: str?}, loyalty_account_id: str, location_id: str, source: str, expire_points: map{loyalty_program_id: str, points: int}, other_event: map{loyalty_program_id: str, points: int}, accumulate_promotion_points: map{loyalty_program_id: str, loyalty_promotion_id: str, points: int, order_id: str}}, events: [map]} # Success @endpoint POST /v2/loyalty/accounts/{account_id}/adjust @desc AdjustLoyaltyPoints @required {account_id: str # The ID of the target [loyalty account](entity:LoyaltyAccount)., idempotency_key: str # A unique string that identifies this `AdjustLoyaltyPoints` request. Keys can be any valid string, but must be unique for every request., adjust_points: map{loyalty_program_id: str, points!: int, reason: str} # Provides metadata when the event `type` is `ADJUST_POINTS`.} @optional {allow_negative_balance: bool # Indicates whether to allow a negative adjustment to result in a negative balance. If `true`, a negative balance is allowed when subtracting points. If `false`, Square returns a `BAD_REQUEST` error when subtracting the specified number of points would result in a negative balance. The default value is `false`.} @returns(200) {errors: [map], event: map{id: str, type: str, created_at: str, accumulate_points: map{loyalty_program_id: str, points: int?, order_id: str?}, create_reward: map{loyalty_program_id: str, reward_id: str, points: int}, redeem_reward: map{loyalty_program_id: str, reward_id: str, order_id: str}, delete_reward: map{loyalty_program_id: str, reward_id: str, points: int}, adjust_points: map{loyalty_program_id: str, points: int, reason: str?}, loyalty_account_id: str, location_id: str, source: str, expire_points: map{loyalty_program_id: str, points: int}, other_event: map{loyalty_program_id: str, points: int}, accumulate_promotion_points: map{loyalty_program_id: str, loyalty_promotion_id: str, points: int, order_id: str}}} # Success @endpoint POST /v2/loyalty/events/search @desc SearchLoyaltyEvents @optional {query: map{filter: map} # Represents a query used to search for loyalty events., limit: int # The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], events: [map], cursor: str} # Success @endpoint GET /v2/loyalty/programs @desc ListLoyaltyPrograms @returns(200) {errors: [map], programs: [map]} # Success @endpoint GET /v2/loyalty/programs/{program_id} @desc RetrieveLoyaltyProgram @required {program_id: str # The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller.} @returns(200) {errors: [map], program: map{id: str, status: str, reward_tiers: [map]?, expiration_policy: map{expiration_duration: str}, terminology: map{one: str, other: str}, location_ids: [str]?, created_at: str, updated_at: str, accrual_rules: [map]?}} # Success @endpoint POST /v2/loyalty/programs/{program_id}/calculate @desc CalculateLoyaltyPoints @required {program_id: str # The ID of the [loyalty program](entity:LoyaltyProgram), which defines the rules for accruing points.} @optional {order_id: str # The [order](entity:Order) ID for which to calculate the points. Specify this field if your application uses the Orders API to process orders. Otherwise, specify the `transaction_amount_money`., transaction_amount_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., loyalty_account_id: str # The ID of the target [loyalty account](entity:LoyaltyAccount). Optionally specify this field if your application uses the Orders API to process orders. If specified, the `promotion_points` field in the response shows the number of points the buyer would earn from the purchase. In this case, Square uses the account ID to determine whether the promotion's `trigger_limit` (the maximum number of times that a buyer can trigger the promotion) has been reached. If not specified, the `promotion_points` field shows the number of points the purchase qualifies for regardless of the trigger limit.} @returns(200) {errors: [map], points: int, promotion_points: int} # Success @endpoint GET /v2/loyalty/programs/{program_id}/promotions @desc ListLoyaltyPromotions @required {program_id: str # The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.} @optional {status: str # The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], loyalty_promotions: [map], cursor: str} # Success @endpoint POST /v2/loyalty/programs/{program_id}/promotions @desc CreateLoyaltyPromotion @required {program_id: str # The ID of the [loyalty program](entity:LoyaltyProgram) to associate with the promotion. To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword., loyalty_promotion: map{id: str, name!: str, incentive!: map, available_time!: map, trigger_limit: map, status: str, created_at: str, canceled_at: str, updated_at: str, loyalty_program_id: str, minimum_spend_amount_money: map, qualifying_item_variation_ids: [str], qualifying_category_ids: [str]} # Represents a promotion for a [loyalty program](entity:LoyaltyProgram). Loyalty promotions enable buyers to earn extra points on top of those earned from the base program. A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status., idempotency_key: str # A unique identifier for this request, which is used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {errors: [map], loyalty_promotion: map{id: str, name: str, incentive: map{type: str, points_multiplier_data: map{points_multiplier: int?, multiplier: str?}, points_addition_data: map{points_addition: int}}, available_time: map{start_date: str, end_date: str, time_periods: [str]}, trigger_limit: map{times: int, interval: str}, status: str, created_at: str, canceled_at: str, updated_at: str, loyalty_program_id: str, minimum_spend_amount_money: map{amount: int(int64)?, currency: str}, qualifying_item_variation_ids: [str]?, qualifying_category_ids: [str]?}} # Success @endpoint GET /v2/loyalty/programs/{program_id}/promotions/{promotion_id} @desc RetrieveLoyaltyPromotion @required {promotion_id: str # The ID of the [loyalty promotion](entity:LoyaltyPromotion) to retrieve., program_id: str # The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword.} @returns(200) {errors: [map], loyalty_promotion: map{id: str, name: str, incentive: map{type: str, points_multiplier_data: map{points_multiplier: int?, multiplier: str?}, points_addition_data: map{points_addition: int}}, available_time: map{start_date: str, end_date: str, time_periods: [str]}, trigger_limit: map{times: int, interval: str}, status: str, created_at: str, canceled_at: str, updated_at: str, loyalty_program_id: str, minimum_spend_amount_money: map{amount: int(int64)?, currency: str}, qualifying_item_variation_ids: [str]?, qualifying_category_ids: [str]?}} # Success @endpoint POST /v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel @desc CancelLoyaltyPromotion @required {promotion_id: str # The ID of the [loyalty promotion](entity:LoyaltyPromotion) to cancel. You can cancel a promotion that has an `ACTIVE` or `SCHEDULED` status., program_id: str # The ID of the base [loyalty program](entity:LoyaltyProgram).} @returns(200) {errors: [map], loyalty_promotion: map{id: str, name: str, incentive: map{type: str, points_multiplier_data: map{points_multiplier: int?, multiplier: str?}, points_addition_data: map{points_addition: int}}, available_time: map{start_date: str, end_date: str, time_periods: [str]}, trigger_limit: map{times: int, interval: str}, status: str, created_at: str, canceled_at: str, updated_at: str, loyalty_program_id: str, minimum_spend_amount_money: map{amount: int(int64)?, currency: str}, qualifying_item_variation_ids: [str]?, qualifying_category_ids: [str]?}} # Success @endpoint POST /v2/loyalty/rewards @desc CreateLoyaltyReward @required {reward: map{id: str, status: str, loyalty_account_id!: str, reward_tier_id!: str, points: int, order_id: str, created_at: str, updated_at: str, redeemed_at: str} # Represents a contract to redeem loyalty points for a [reward tier](entity:LoyaltyProgramRewardTier) discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see [Manage loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards)., idempotency_key: str # A unique string that identifies this `CreateLoyaltyReward` request. Keys can be any valid string, but must be unique for every request.} @returns(200) {errors: [map], reward: map{id: str, status: str, loyalty_account_id: str, reward_tier_id: str, points: int, order_id: str?, created_at: str, updated_at: str, redeemed_at: str}} # Success @endpoint POST /v2/loyalty/rewards/search @desc SearchLoyaltyRewards @optional {query: map{loyalty_account_id!: str, status: str} # The set of search requirements., limit: int # The maximum number of results to return in the response. The default value is 30., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {errors: [map], rewards: [map], cursor: str} # Success @endpoint DELETE /v2/loyalty/rewards/{reward_id} @desc DeleteLoyaltyReward @required {reward_id: str # The ID of the [loyalty reward](entity:LoyaltyReward) to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/loyalty/rewards/{reward_id} @desc RetrieveLoyaltyReward @required {reward_id: str # The ID of the [loyalty reward](entity:LoyaltyReward) to retrieve.} @returns(200) {errors: [map], reward: map{id: str, status: str, loyalty_account_id: str, reward_tier_id: str, points: int, order_id: str?, created_at: str, updated_at: str, redeemed_at: str}} # Success @endpoint POST /v2/loyalty/rewards/{reward_id}/redeem @desc RedeemLoyaltyReward @required {reward_id: str # The ID of the [loyalty reward](entity:LoyaltyReward) to redeem., idempotency_key: str # A unique string that identifies this `RedeemLoyaltyReward` request. Keys can be any valid string, but must be unique for every request., location_id: str # The ID of the [location](entity:Location) where the reward is redeemed.} @returns(200) {errors: [map], event: map{id: str, type: str, created_at: str, accumulate_points: map{loyalty_program_id: str, points: int?, order_id: str?}, create_reward: map{loyalty_program_id: str, reward_id: str, points: int}, redeem_reward: map{loyalty_program_id: str, reward_id: str, order_id: str}, delete_reward: map{loyalty_program_id: str, reward_id: str, points: int}, adjust_points: map{loyalty_program_id: str, points: int, reason: str?}, loyalty_account_id: str, location_id: str, source: str, expire_points: map{loyalty_program_id: str, points: int}, other_event: map{loyalty_program_id: str, points: int}, accumulate_promotion_points: map{loyalty_program_id: str, loyalty_promotion_id: str, points: int, order_id: str}}} # Success @endgroup @group merchants @endpoint GET /v2/merchants @desc ListMerchants @optional {cursor: int # The cursor generated by the previous response.} @returns(200) {errors: [map], merchant: [map], cursor: int} # Success @endpoint GET /v2/merchants/custom-attribute-definitions @desc ListMerchantCustomAttributeDefinitions @optional {visibility_filter: str # Filters the `CustomAttributeDefinition` results by their `visibility` values., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {custom_attribute_definitions: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/merchants/custom-attribute-definitions @desc CreateMerchantCustomAttributeDefinition @required {custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/merchants/custom-attribute-definitions/{key} @desc DeleteMerchantCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/merchants/custom-attribute-definitions/{key} @desc RetrieveMerchantCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.} @optional {version: int # The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/merchants/custom-attribute-definitions/{key} @desc UpdateMerchantCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to update., custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/merchants/custom-attributes/bulk-delete @desc BulkDeleteMerchantCustomAttributes @required {values: map # The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response.} @returns(200) {values: map, errors: [map]} # Success @endpoint POST /v2/merchants/custom-attributes/bulk-upsert @desc BulkUpsertMerchantCustomAttributes @required {values: map # A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this `BulkUpsertMerchantCustomAttributes` request and the information needed to create or update a custom attribute.} @returns(200) {values: map, errors: [map]} # Success @endpoint GET /v2/merchants/{merchant_id} @desc RetrieveMerchant @required {merchant_id: str # The ID of the merchant to retrieve. If the string "me" is supplied as the ID, then retrieve the merchant that is currently accessible to this call.} @returns(200) {errors: [map], merchant: map{id: str, business_name: str?, country: str, language_code: str?, currency: str, status: str, main_location_id: str?, created_at: str}} # Success @endpoint GET /v2/merchants/{merchant_id}/custom-attributes @desc ListMerchantCustomAttributes @required {merchant_id: str # The ID of the target [merchant](entity:Merchant).} @optional {visibility_filter: str # Filters the `CustomAttributeDefinition` results by their `visibility` values., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., with_definitions: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attributes: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/merchants/{merchant_id}/custom-attributes/{key} @desc DeleteMerchantCustomAttribute @required {merchant_id: str # The ID of the target [merchant](entity:Merchant)., key: str # The key of the custom attribute to delete. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/merchants/{merchant_id}/custom-attributes/{key} @desc RetrieveMerchantCustomAttribute @required {merchant_id: str # The ID of the target [merchant](entity:Merchant)., key: str # The key of the custom attribute to retrieve. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.} @optional {with_definition: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of the custom attribute. Set this parameter to `true` to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is `false`., version: int # The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a `BAD_REQUEST` error.} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/merchants/{merchant_id}/custom-attributes/{key} @desc UpsertMerchantCustomAttribute @required {merchant_id: str # The ID of the target [merchant](entity:Merchant)., key: str # The key of the custom attribute to create or update. This key must match the `key` of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key., custom_attribute: map{key: str, value: any, version: int, visibility: str, definition: map, updated_at: str, created_at: str} # A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endgroup @group online-checkout @endpoint GET /v2/online-checkout/location-settings/{location_id} @desc RetrieveLocationSettings @required {location_id: str # The ID of the location for which to retrieve settings.} @returns(200) {errors: [map], location_settings: map{location_id: str?, customer_notes_enabled: bool?, policies: [map]?, branding: map{header_type: str, button_color: str?, button_shape: str}, tipping: map{percentages: [int]?, smart_tipping_enabled: bool?, default_percent: int?, smart_tips: [map]?, default_smart_tip: map{amount: int(int64)?, currency: str}}, coupons: map{enabled: bool?}, updated_at: str}} # Success @endpoint PUT /v2/online-checkout/location-settings/{location_id} @desc UpdateLocationSettings @required {location_id: str # The ID of the location for which to retrieve settings., location_settings: map{location_id: str, customer_notes_enabled: bool, policies: [map], branding: map, tipping: map, coupons: map, updated_at: str}} @returns(200) {errors: [map], location_settings: map{location_id: str?, customer_notes_enabled: bool?, policies: [map]?, branding: map{header_type: str, button_color: str?, button_shape: str}, tipping: map{percentages: [int]?, smart_tipping_enabled: bool?, default_percent: int?, smart_tips: [map]?, default_smart_tip: map{amount: int(int64)?, currency: str}}, coupons: map{enabled: bool?}, updated_at: str}} # Success @endpoint GET /v2/online-checkout/merchant-settings @desc RetrieveMerchantSettings @returns(200) {errors: [map], merchant_settings: map{payment_methods: map{apple_pay: map{enabled: bool?}, google_pay: map{enabled: bool?}, cash_app: map{enabled: bool?}, afterpay_clearpay: map{order_eligibility_range: map, item_eligibility_range: map, enabled: bool}}, updated_at: str}} # Success @endpoint PUT /v2/online-checkout/merchant-settings @desc UpdateMerchantSettings @required {merchant_settings: map{payment_methods: map, updated_at: str}} @returns(200) {errors: [map], merchant_settings: map{payment_methods: map{apple_pay: map{enabled: bool?}, google_pay: map{enabled: bool?}, cash_app: map{enabled: bool?}, afterpay_clearpay: map{order_eligibility_range: map, item_eligibility_range: map, enabled: bool}}, updated_at: str}} # Success @endpoint GET /v2/online-checkout/payment-links @desc ListPaymentLinks @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored. Default value: `100`} @returns(200) {errors: [map], payment_links: [map], cursor: str} # Success @endpoint POST /v2/online-checkout/payment-links @desc CreatePaymentLink @optional {idempotency_key: str # A unique string that identifies this `CreatePaymentLinkRequest` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)., description: str # A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere., quick_pay: map{name!: str, price_money!: map, location_id!: str} # Describes an ad hoc item and price to generate a quick pay checkout link. For more information, see [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout)., order: map{id: str, location_id!: str, reference_id: str, source: map, customer_id: str, line_items: [map], taxes: [map], discounts: [map], service_charges: [map], fulfillments: [map], returns: [map], return_amounts: map, net_amounts: map, rounding_adjustment: map, tenders: [map], refunds: [map], metadata: map, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map, total_tax_money: map, total_discount_money: map, total_tip_money: map, total_service_charge_money: map, ticket_name: str, pricing_options: map, rewards: [map], net_amount_due_money: map} # Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data., checkout_options: map{allow_tipping: bool, custom_fields: [map], subscription_plan_id: str, redirect_url: str, merchant_support_email: str, ask_for_shipping_address: bool, accepted_payment_methods: map, app_fee_money: map, shipping_fee: map, enable_coupon: bool, enable_loyalty: bool}, pre_populated_data: map{buyer_email: str, buyer_phone_number: str, buyer_address: map} # Describes buyer data to prepopulate in the payment form. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations)., payment_note: str # A note for the payment. After processing the payment, Square adds this note to the resulting `Payment`.} @returns(200) {errors: [map], payment_link: map{id: str, version: int, description: str?, order_id: str, checkout_options: map{allow_tipping: bool?, custom_fields: [map]?, subscription_plan_id: str?, redirect_url: str?, merchant_support_email: str?, ask_for_shipping_address: bool?, accepted_payment_methods: map{apple_pay: bool?, google_pay: bool?, cash_app_pay: bool?, afterpay_clearpay: bool?}, app_fee_money: map{amount: int(int64)?, currency: str}, shipping_fee: map{name: str?, charge: map}, enable_coupon: bool?, enable_loyalty: bool?}, pre_populated_data: map{buyer_email: str?, buyer_phone_number: str?, buyer_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, url: str, long_url: str, created_at: str, updated_at: str, payment_note: str?}, related_resources: map{orders: [map]?, subscription_plans: [map]?}} # Success @endpoint DELETE /v2/online-checkout/payment-links/{id} @desc DeletePaymentLink @required {id: str # The ID of the payment link to delete.} @returns(200) {errors: [map], id: str, cancelled_order_id: str} # Success @endpoint GET /v2/online-checkout/payment-links/{id} @desc RetrievePaymentLink @required {id: str # The ID of link to retrieve.} @returns(200) {errors: [map], payment_link: map{id: str, version: int, description: str?, order_id: str, checkout_options: map{allow_tipping: bool?, custom_fields: [map]?, subscription_plan_id: str?, redirect_url: str?, merchant_support_email: str?, ask_for_shipping_address: bool?, accepted_payment_methods: map{apple_pay: bool?, google_pay: bool?, cash_app_pay: bool?, afterpay_clearpay: bool?}, app_fee_money: map{amount: int(int64)?, currency: str}, shipping_fee: map{name: str?, charge: map}, enable_coupon: bool?, enable_loyalty: bool?}, pre_populated_data: map{buyer_email: str?, buyer_phone_number: str?, buyer_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, url: str, long_url: str, created_at: str, updated_at: str, payment_note: str?}} # Success @endpoint PUT /v2/online-checkout/payment-links/{id} @desc UpdatePaymentLink @required {id: str # The ID of the payment link to update., payment_link: map{id: str, version!: int, description: str, order_id: str, checkout_options: map, pre_populated_data: map, url: str, long_url: str, created_at: str, updated_at: str, payment_note: str}} @returns(200) {errors: [map], payment_link: map{id: str, version: int, description: str?, order_id: str, checkout_options: map{allow_tipping: bool?, custom_fields: [map]?, subscription_plan_id: str?, redirect_url: str?, merchant_support_email: str?, ask_for_shipping_address: bool?, accepted_payment_methods: map{apple_pay: bool?, google_pay: bool?, cash_app_pay: bool?, afterpay_clearpay: bool?}, app_fee_money: map{amount: int(int64)?, currency: str}, shipping_fee: map{name: str?, charge: map}, enable_coupon: bool?, enable_loyalty: bool?}, pre_populated_data: map{buyer_email: str?, buyer_phone_number: str?, buyer_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}}, url: str, long_url: str, created_at: str, updated_at: str, payment_note: str?}} # Success @endgroup @group orders @endpoint POST /v2/orders @desc CreateOrder @optional {order: map{id: str, location_id!: str, reference_id: str, source: map, customer_id: str, line_items: [map], taxes: [map], discounts: [map], service_charges: [map], fulfillments: [map], returns: [map], return_amounts: map, net_amounts: map, rounding_adjustment: map, tenders: [map], refunds: [map], metadata: map, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map, total_tax_money: map, total_discount_money: map, total_tip_money: map, total_service_charge_money: map, ticket_name: str, pricing_options: map, rewards: [map], net_amount_due_money: map} # Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data., idempotency_key: str # A value you specify that uniquely identifies this order among orders you have created. If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint POST /v2/orders/batch-retrieve @desc BatchRetrieveOrders @required {order_ids: [str] # The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.} @optional {location_id: str # The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID.} @returns(200) {orders: [map], errors: [map]} # Success @endpoint POST /v2/orders/calculate @desc CalculateOrder @required {order: map{id: str, location_id!: str, reference_id: str, source: map, customer_id: str, line_items: [map], taxes: [map], discounts: [map], service_charges: [map], fulfillments: [map], returns: [map], return_amounts: map, net_amounts: map, rounding_adjustment: map, tenders: [map], refunds: [map], metadata: map, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map, total_tax_money: map, total_discount_money: map, total_tip_money: map, total_service_charge_money: map, ticket_name: str, pricing_options: map, rewards: [map], net_amount_due_money: map} # Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.} @optional {proposed_rewards: [map{id!: str, reward_tier_id!: str}] # Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards. The rewards do not correspond to actual redemptions; that is, no `reward`s are created. Therefore, the reward `id`s are random strings used only to reference the reward tier.} @returns(200) {order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint POST /v2/orders/clone @desc CloneOrder @required {order_id: str # The ID of the order to clone.} @optional {version: int # An optional order version for concurrency protection. If a version is provided, it must match the latest stored version of the order to clone. If a version is not provided, the API clones the latest version., idempotency_key: str # A value you specify that uniquely identifies this clone request. If you are unsure whether a particular order was cloned successfully, you can reattempt the call with the same idempotency key without worrying about creating duplicate cloned orders. The originally cloned order is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint GET /v2/orders/custom-attribute-definitions @desc ListOrderCustomAttributeDefinitions @optional {visibility_filter: str # Requests that all of the custom attributes be returned, or only those that are read-only or read-write., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).} @returns(200) {custom_attribute_definitions: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/orders/custom-attribute-definitions @desc CreateOrderCustomAttributeDefinition @required {custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint DELETE /v2/orders/custom-attribute-definitions/{key} @desc DeleteOrderCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/orders/custom-attribute-definitions/{key} @desc RetrieveOrderCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to retrieve.} @optional {version: int # To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute.} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint PUT /v2/orders/custom-attribute-definitions/{key} @desc UpdateOrderCustomAttributeDefinition @required {key: str # The key of the custom attribute definition to update., custom_attribute_definition: map{key: str, schema: map, name: str, description: str, visibility: str, version: int, updated_at: str, created_at: str} # Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute_definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/orders/custom-attributes/bulk-delete @desc BulkDeleteOrderCustomAttributes @required {values: map # A map of requests that correspond to individual delete operations for custom attributes.} @returns(200) {errors: [map], values: map} # Success @endpoint POST /v2/orders/custom-attributes/bulk-upsert @desc BulkUpsertOrderCustomAttributes @required {values: map # A map of requests that correspond to individual upsert operations for custom attributes.} @returns(200) {errors: [map], values: map} # Success @endpoint POST /v2/orders/search @desc SearchOrders @optional {location_ids: [str] # The location IDs for the orders to query. All locations must belong to the same merchant. Max: 10 location IDs., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., query: map{filter: map, sort: map} # Contains query criteria for the search., limit: int # The maximum number of results to be returned in a single page. Default: `500` Max: `1000`, return_entries: bool # A Boolean that controls the format of the search results. If `true`, `SearchOrders` returns [OrderEntry](entity:OrderEntry) objects. If `false`, `SearchOrders` returns complete order objects. Default: `false`.} @returns(200) {order_entries: [map], orders: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/orders/{order_id} @desc RetrieveOrder @required {order_id: str # The ID of the order to retrieve.} @returns(200) {order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint PUT /v2/orders/{order_id} @desc UpdateOrder @required {order_id: str # The ID of the order to update.} @optional {order: map{id: str, location_id!: str, reference_id: str, source: map, customer_id: str, line_items: [map], taxes: [map], discounts: [map], service_charges: [map], fulfillments: [map], returns: [map], return_amounts: map, net_amounts: map, rounding_adjustment: map, tenders: [map], refunds: [map], metadata: map, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map, total_tax_money: map, total_discount_money: map, total_tip_money: map, total_service_charge_money: map, ticket_name: str, pricing_options: map, rewards: [map], net_amount_due_money: map} # Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data., fields_to_clear: [str] # The [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete) fields to clear. For example, `line_items[uid].note`. For more information, see [Deleting fields](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#deleting-fields)., idempotency_key: str # A value you specify that uniquely identifies this update request. If you are unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version is returned. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}, errors: [map]} # Success @endpoint GET /v2/orders/{order_id}/custom-attributes @desc ListOrderCustomAttributes @required {order_id: str # The ID of the target [order](entity:Order).} @optional {visibility_filter: str # Requests that all of the custom attributes be returned, or only those that are read-only or read-write., cursor: str # The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., limit: int # The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)., with_definitions: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attributes: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/orders/{order_id}/custom-attributes/{custom_attribute_key} @desc DeleteOrderCustomAttribute @required {order_id: str # The ID of the target [order](entity:Order)., custom_attribute_key: str # The key of the custom attribute to delete. This key must match the key of an existing custom attribute definition.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/orders/{order_id}/custom-attributes/{custom_attribute_key} @desc RetrieveOrderCustomAttribute @required {order_id: str # The ID of the target [order](entity:Order)., custom_attribute_key: str # The key of the custom attribute to retrieve. This key must match the key of an existing custom attribute definition.} @optional {version: int # To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control, include this optional field and specify the current version of the custom attribute., with_definition: bool=false # Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`.} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/orders/{order_id}/custom-attributes/{custom_attribute_key} @desc UpsertOrderCustomAttribute @required {order_id: str # The ID of the target [order](entity:Order)., custom_attribute_key: str # The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition., custom_attribute: map{key: str, value: any, version: int, visibility: str, definition: map, updated_at: str, created_at: str} # A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.} @optional {idempotency_key: str # A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {custom_attribute: map{key: str?, value: any?, version: int, visibility: str, definition: map{key: str?, schema: map?, name: str?, description: str?, visibility: str, version: int, updated_at: str, created_at: str}, updated_at: str, created_at: str}, errors: [map]} # Success @endpoint POST /v2/orders/{order_id}/pay @desc PayOrder @required {order_id: str # The ID of the order being paid., idempotency_key: str # A value you specify that uniquely identifies this request among requests you have sent. If you are unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).} @optional {order_version: int # The version of the order being paid. If not supplied, the latest version will be paid., payment_ids: [str] # The IDs of the [payments](entity:Payment) to collect. The payment total must match the order total.} @returns(200) {errors: [map], order: map{id: str, location_id: str, reference_id: str?, source: map{name: str?}, customer_id: str?, line_items: [map]?, taxes: [map]?, discounts: [map]?, service_charges: [map]?, fulfillments: [map]?, returns: [map], return_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, net_amounts: map{total_money: map{amount: int(int64)?, currency: str}, tax_money: map{amount: int(int64)?, currency: str}, discount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, service_charge_money: map{amount: int(int64)?, currency: str}}, rounding_adjustment: map{uid: str?, name: str?, amount_money: map{amount: int(int64)?, currency: str}}, tenders: [map], refunds: [map], metadata: map?, created_at: str, updated_at: str, closed_at: str, state: str, version: int, total_money: map{amount: int(int64)?, currency: str}, total_tax_money: map{amount: int(int64)?, currency: str}, total_discount_money: map{amount: int(int64)?, currency: str}, total_tip_money: map{amount: int(int64)?, currency: str}, total_service_charge_money: map{amount: int(int64)?, currency: str}, ticket_name: str?, pricing_options: map{auto_apply_discounts: bool?, auto_apply_taxes: bool?}, rewards: [map], net_amount_due_money: map{amount: int(int64)?, currency: str}}} # Success @endgroup @group payments @endpoint GET /v2/payments @desc ListPayments @optional {begin_time: str # Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Inclusive. Default: The current time minus one year., end_time: str # Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Default: The current time., sort_order: str # The order in which results are listed by `ListPaymentsRequest.sort_field`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., location_id: str # Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller., total: int(int64) # The exact amount in the `total_money` for a payment., last_4: str # The last four digits of a payment card., card_brand: str # The brand of the payment card (for example, VISA)., limit: int # The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`, is_offline_payment: bool=false # Whether the payment was taken offline or not., offline_begin_time: str # Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the `offline_payment_details.client_created_at` field for each Payment. If set, payments without a value set in `offline_payment_details.client_created_at` will not be returned. Default: The current time., offline_end_time: str # Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the `offline_payment_details.client_created_at` field for each Payment. If set, payments without a value set in `offline_payment_details.client_created_at` will not be returned. Default: The current time., updated_at_begin_time: str # Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `updated_at` field for each Payment., updated_at_end_time: str # Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `updated_at` field for each Payment., sort_field: str # The field used to sort results by. The default is `CREATED_AT`.} @returns(200) {errors: [map], payments: [map], cursor: str} # Success @endpoint POST /v2/payments @desc CreatePayment @required {source_id: str # The ID for the source of funds for this payment. This could be a payment token generated by the Web Payments SDK for any of its [supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods), including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment that the seller received outside of Square, specify either "CASH" or "EXTERNAL". For more information, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments)., idempotency_key: str # A unique string that identifies this `CreatePayment` request. Keys can be any valid string but must be unique for every `CreatePayment` request. Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).} @optional {amount_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., tip_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., app_fee_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., delay_duration: str # The duration of time after the payment's creation when Square automatically either completes or cancels the payment depending on the `delay_action` field value. For more information, see [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). This parameter should be specified as a time duration, in RFC 3339 format. Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (`autocomplete=false`). Default: - Card-present payments: "PT36H" (36 hours) from the creation time. - Card-not-present payments: "P7D" (7 days) from the creation time., delay_action: str # The action to be applied to the payment when the `delay_duration` has elapsed. The action must be CANCEL or COMPLETE. For more information, see [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). Default: CANCEL, autocomplete: bool # If set to `true`, this payment will be completed when possible. If set to `false`, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see [Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment). Default: true, order_id: str # Associates a previously created order with this payment., customer_id: str # The [Customer](entity:Customer) ID of the customer associated with the payment. This is required if the `source_id` refers to a card on file created using the Cards API., location_id: str # The location ID to associate with the payment. If not specified, the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location) is used., team_member_id: str # An optional [TeamMember](entity:TeamMember) ID to associate with this payment., reference_id: str # A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart)., verification_token: str # An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview)., accept_partial_authorization: bool # If set to `true` and charging a Square Gift Card, a payment might be returned with `amount_money` equal to less than what was requested. For example, a request for $20 when charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment. This field cannot be `true` when `autocomplete = true`. For more information, see [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card). Default: false, buyer_email_address: str # The buyer's email address., buyer_phone_number: str # The buyer's phone number. Must follow the following format: 1. A leading + symbol (followed by a country code) 2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`. Alphabetical characters aren't allowed. 3. The phone number must contain between 9 and 16 digits., billing_address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., shipping_address: map{address_line_1: str, address_line_2: str, address_line_3: str, locality: str, sublocality: str, sublocality_2: str, sublocality_3: str, administrative_district_level_1: str, administrative_district_level_2: str, administrative_district_level_3: str, postal_code: str, country: str, first_name: str, last_name: str} # Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)., note: str # An optional note to be entered by the developer when creating a payment., statement_description_identifier: str # Optional additional payment information to include on the customer's card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase. Note that the `statement_description_identifier` might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and name of the seller taking the payment., cash_details: map{buyer_supplied_money!: map, change_back_money: map} # Stores details about a cash payment. Contains only non-confidential information. For more information, see [Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments)., external_details: map{type!: str, source!: str, source_id: str, source_fee_money: map} # Stores details about an external payment. Contains only non-confidential information. For more information, see [Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments)., customer_details: map{customer_initiated: bool, seller_keyed_in: bool} # Details about the customer making the payment., offline_payment_details: map{client_created_at: str} # Details specific to offline payments.} @returns(200) {errors: [map], payment: map{id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, total_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, approved_money: map{amount: int(int64)?, currency: str}, processing_fee: [map], refunded_money: map{amount: int(int64)?, currency: str}, status: str, delay_duration: str, delay_action: str?, delayed_until: str, source_type: str, card_details: map{status: str, card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}, entry_method: str, cvv_status: str, avs_status: str, auth_result_code: str, application_identifier: str, application_name: str, application_cryptogram: str, verification_method: str, verification_results: str, statement_description: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, card_payment_timeline: map{authorized_at: str?, captured_at: str?, voided_at: str?}, refund_requires_card_presence: bool, errors: [map]}, cash_details: map{buyer_supplied_money: map{amount: int(int64)?, currency: str}, change_back_money: map{amount: int(int64)?, currency: str}}, bank_account_details: map{bank_name: str?, transfer_type: str?, account_ownership_type: str?, fingerprint: str?, country: str?, statement_description: str?, ach_details: map{routing_number: str?, account_number_suffix: str?, account_type: str?}, errors: [map]?}, external_details: map{type: str, source: str, source_id: str?, source_fee_money: map{amount: int(int64)?, currency: str}}, wallet_details: map{status: str?, brand: str?, cash_app_details: map{buyer_full_name: str?, buyer_country_code: str?, buyer_cashtag: str}}, buy_now_pay_later_details: map{brand: str?, afterpay_details: map{email_address: str?}, clearpay_details: map{email_address: str?}}, square_account_details: map{payment_source_token: str?, errors: [map]?}, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str?, refund_ids: [str], risk_evaluation: map{created_at: str, risk_level: str}, terminal_checkout_id: str, buyer_email_address: str, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, application_details: map{square_product: str, application_id: str?}, is_offline_payment: bool, offline_payment_details: map{client_created_at: str}, version_token: str?}} # Success @endpoint POST /v2/payments/cancel @desc CancelPaymentByIdempotencyKey @required {idempotency_key: str # The `idempotency_key` identifying the payment to be canceled.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/payments/{payment_id} @desc GetPayment @required {payment_id: str # A unique ID for the desired payment.} @returns(200) {errors: [map], payment: map{id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, total_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, approved_money: map{amount: int(int64)?, currency: str}, processing_fee: [map], refunded_money: map{amount: int(int64)?, currency: str}, status: str, delay_duration: str, delay_action: str?, delayed_until: str, source_type: str, card_details: map{status: str, card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}, entry_method: str, cvv_status: str, avs_status: str, auth_result_code: str, application_identifier: str, application_name: str, application_cryptogram: str, verification_method: str, verification_results: str, statement_description: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, card_payment_timeline: map{authorized_at: str?, captured_at: str?, voided_at: str?}, refund_requires_card_presence: bool, errors: [map]}, cash_details: map{buyer_supplied_money: map{amount: int(int64)?, currency: str}, change_back_money: map{amount: int(int64)?, currency: str}}, bank_account_details: map{bank_name: str?, transfer_type: str?, account_ownership_type: str?, fingerprint: str?, country: str?, statement_description: str?, ach_details: map{routing_number: str?, account_number_suffix: str?, account_type: str?}, errors: [map]?}, external_details: map{type: str, source: str, source_id: str?, source_fee_money: map{amount: int(int64)?, currency: str}}, wallet_details: map{status: str?, brand: str?, cash_app_details: map{buyer_full_name: str?, buyer_country_code: str?, buyer_cashtag: str}}, buy_now_pay_later_details: map{brand: str?, afterpay_details: map{email_address: str?}, clearpay_details: map{email_address: str?}}, square_account_details: map{payment_source_token: str?, errors: [map]?}, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str?, refund_ids: [str], risk_evaluation: map{created_at: str, risk_level: str}, terminal_checkout_id: str, buyer_email_address: str, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, application_details: map{square_product: str, application_id: str?}, is_offline_payment: bool, offline_payment_details: map{client_created_at: str}, version_token: str?}} # Success @endpoint PUT /v2/payments/{payment_id} @desc UpdatePayment @required {payment_id: str # The ID of the payment to update., idempotency_key: str # A unique string that identifies this `UpdatePayment` request. Keys can be any valid string but must be unique for every `UpdatePayment` request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @optional {payment: map{id: str, created_at: str, updated_at: str, amount_money: map, tip_money: map, total_money: map, app_fee_money: map, approved_money: map, processing_fee: [map], refunded_money: map, status: str, delay_duration: str, delay_action: str, delayed_until: str, source_type: str, card_details: map, cash_details: map, bank_account_details: map, external_details: map, wallet_details: map, buy_now_pay_later_details: map, square_account_details: map, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str, refund_ids: [str], risk_evaluation: map, terminal_checkout_id: str, buyer_email_address: str, billing_address: map, shipping_address: map, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map, application_details: map, is_offline_payment: bool, offline_payment_details: map, version_token: str} # Represents a payment processed by the Square API.} @returns(200) {errors: [map], payment: map{id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, total_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, approved_money: map{amount: int(int64)?, currency: str}, processing_fee: [map], refunded_money: map{amount: int(int64)?, currency: str}, status: str, delay_duration: str, delay_action: str?, delayed_until: str, source_type: str, card_details: map{status: str, card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}, entry_method: str, cvv_status: str, avs_status: str, auth_result_code: str, application_identifier: str, application_name: str, application_cryptogram: str, verification_method: str, verification_results: str, statement_description: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, card_payment_timeline: map{authorized_at: str?, captured_at: str?, voided_at: str?}, refund_requires_card_presence: bool, errors: [map]}, cash_details: map{buyer_supplied_money: map{amount: int(int64)?, currency: str}, change_back_money: map{amount: int(int64)?, currency: str}}, bank_account_details: map{bank_name: str?, transfer_type: str?, account_ownership_type: str?, fingerprint: str?, country: str?, statement_description: str?, ach_details: map{routing_number: str?, account_number_suffix: str?, account_type: str?}, errors: [map]?}, external_details: map{type: str, source: str, source_id: str?, source_fee_money: map{amount: int(int64)?, currency: str}}, wallet_details: map{status: str?, brand: str?, cash_app_details: map{buyer_full_name: str?, buyer_country_code: str?, buyer_cashtag: str}}, buy_now_pay_later_details: map{brand: str?, afterpay_details: map{email_address: str?}, clearpay_details: map{email_address: str?}}, square_account_details: map{payment_source_token: str?, errors: [map]?}, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str?, refund_ids: [str], risk_evaluation: map{created_at: str, risk_level: str}, terminal_checkout_id: str, buyer_email_address: str, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, application_details: map{square_product: str, application_id: str?}, is_offline_payment: bool, offline_payment_details: map{client_created_at: str}, version_token: str?}} # Success @endpoint POST /v2/payments/{payment_id}/cancel @desc CancelPayment @required {payment_id: str # The ID of the payment to cancel.} @returns(200) {errors: [map], payment: map{id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, total_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, approved_money: map{amount: int(int64)?, currency: str}, processing_fee: [map], refunded_money: map{amount: int(int64)?, currency: str}, status: str, delay_duration: str, delay_action: str?, delayed_until: str, source_type: str, card_details: map{status: str, card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}, entry_method: str, cvv_status: str, avs_status: str, auth_result_code: str, application_identifier: str, application_name: str, application_cryptogram: str, verification_method: str, verification_results: str, statement_description: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, card_payment_timeline: map{authorized_at: str?, captured_at: str?, voided_at: str?}, refund_requires_card_presence: bool, errors: [map]}, cash_details: map{buyer_supplied_money: map{amount: int(int64)?, currency: str}, change_back_money: map{amount: int(int64)?, currency: str}}, bank_account_details: map{bank_name: str?, transfer_type: str?, account_ownership_type: str?, fingerprint: str?, country: str?, statement_description: str?, ach_details: map{routing_number: str?, account_number_suffix: str?, account_type: str?}, errors: [map]?}, external_details: map{type: str, source: str, source_id: str?, source_fee_money: map{amount: int(int64)?, currency: str}}, wallet_details: map{status: str?, brand: str?, cash_app_details: map{buyer_full_name: str?, buyer_country_code: str?, buyer_cashtag: str}}, buy_now_pay_later_details: map{brand: str?, afterpay_details: map{email_address: str?}, clearpay_details: map{email_address: str?}}, square_account_details: map{payment_source_token: str?, errors: [map]?}, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str?, refund_ids: [str], risk_evaluation: map{created_at: str, risk_level: str}, terminal_checkout_id: str, buyer_email_address: str, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, application_details: map{square_product: str, application_id: str?}, is_offline_payment: bool, offline_payment_details: map{client_created_at: str}, version_token: str?}} # Success @endpoint POST /v2/payments/{payment_id}/complete @desc CompletePayment @required {payment_id: str # The unique ID identifying the payment to be completed.} @optional {version_token: str # Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned.} @returns(200) {errors: [map], payment: map{id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, tip_money: map{amount: int(int64)?, currency: str}, total_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, approved_money: map{amount: int(int64)?, currency: str}, processing_fee: [map], refunded_money: map{amount: int(int64)?, currency: str}, status: str, delay_duration: str, delay_action: str?, delayed_until: str, source_type: str, card_details: map{status: str, card: map{id: str, card_brand: str, last_4: str, exp_month: int(int64)?, exp_year: int(int64)?, cardholder_name: str?, billing_address: map, fingerprint: str, customer_id: str?, merchant_id: str, reference_id: str?, enabled: bool, card_type: str, prepaid_type: str, bin: str, version: int(int64), card_co_brand: str, issuer_alert: str, issuer_alert_at: str, hsa_fsa: bool}, entry_method: str, cvv_status: str, avs_status: str, auth_result_code: str, application_identifier: str, application_name: str, application_cryptogram: str, verification_method: str, verification_results: str, statement_description: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, card_payment_timeline: map{authorized_at: str?, captured_at: str?, voided_at: str?}, refund_requires_card_presence: bool, errors: [map]}, cash_details: map{buyer_supplied_money: map{amount: int(int64)?, currency: str}, change_back_money: map{amount: int(int64)?, currency: str}}, bank_account_details: map{bank_name: str?, transfer_type: str?, account_ownership_type: str?, fingerprint: str?, country: str?, statement_description: str?, ach_details: map{routing_number: str?, account_number_suffix: str?, account_type: str?}, errors: [map]?}, external_details: map{type: str, source: str, source_id: str?, source_fee_money: map{amount: int(int64)?, currency: str}}, wallet_details: map{status: str?, brand: str?, cash_app_details: map{buyer_full_name: str?, buyer_country_code: str?, buyer_cashtag: str}}, buy_now_pay_later_details: map{brand: str?, afterpay_details: map{email_address: str?}, clearpay_details: map{email_address: str?}}, square_account_details: map{payment_source_token: str?, errors: [map]?}, location_id: str, order_id: str, reference_id: str, customer_id: str, employee_id: str, team_member_id: str?, refund_ids: [str], risk_evaluation: map{created_at: str, risk_level: str}, terminal_checkout_id: str, buyer_email_address: str, billing_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, shipping_address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, note: str, statement_description_identifier: str, capabilities: [str], receipt_number: str, receipt_url: str, device_details: map{device_id: str?, device_installation_id: str?, device_name: str?}, application_details: map{square_product: str, application_id: str?}, is_offline_payment: bool, offline_payment_details: map{client_created_at: str}, version_token: str?}} # Success @endgroup @group payouts @endpoint GET /v2/payouts @desc ListPayouts @optional {location_id: str # The ID of the location for which to list the payouts. By default, payouts are returned for the default (main) location associated with the seller., status: str # If provided, only payouts with the given status are returned., begin_time: str # The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year., end_time: str # The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time., sort_order: str # The order in which payouts are listed., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). If request parameters change between requests, subsequent results may contain duplicates or missing records., limit: int # The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`} @returns(200) {payouts: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/payouts/{payout_id} @desc GetPayout @required {payout_id: str # The ID of the payout to retrieve the information for.} @returns(200) {payout: map{id: str, status: str, location_id: str, created_at: str, updated_at: str, amount_money: map{amount: int(int64)?, currency: str}, destination: map{type: str, id: str}, version: int, type: str, payout_fee: [map]?, arrival_date: str?, end_to_end_id: str?}, errors: [map]} # Success @endpoint GET /v2/payouts/{payout_id}/payout-entries @desc ListPayoutEntries @required {payout_id: str # The ID of the payout to retrieve the information for.} @optional {sort_order: str # The order in which payout entries are listed., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). If request parameters change between requests, subsequent results may contain duplicates or missing records., limit: int # The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`} @returns(200) {payout_entries: [map], cursor: str, errors: [map]} # Success @endgroup @group refunds @endpoint GET /v2/refunds @desc ListPaymentRefunds @optional {begin_time: str # Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time minus one year., end_time: str # Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time., sort_order: str # The order in which results are listed by `PaymentRefund.created_at`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., location_id: str # Limit results to the location supplied. By default, results are returned for all locations associated with the seller., status: str # If provided, only refunds with the given status are returned. For a list of refund status values, see [PaymentRefund](entity:PaymentRefund). Default: If omitted, refunds are returned regardless of their status., source_type: str # If provided, only returns refunds whose payments have the indicated source type. Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`. For information about these payment source types, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments). Default: If omitted, refunds are returned regardless of the source type., limit: int # The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100, updated_at_begin_time: str # Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: If omitted, the time range starts at `begin_time`., updated_at_end_time: str # Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: The current time., sort_field: str # The field used to sort results by. The default is `CREATED_AT`.} @returns(200) {errors: [map], refunds: [map], cursor: str} # Success @endpoint POST /v2/refunds @desc RefundPayment @required {idempotency_key: str # A unique string that identifies this `RefundPayment` request. The key can be any valid string but must be unique for every `RefundPayment` request. Keys are limited to a max of 45 characters - however, the number of allowed characters might be less than 45, if multi-byte characters are used. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)., amount_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.} @optional {app_fee_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., payment_id: str # The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set., destination_id: str # The ID indicating where funds will be refunded to. Required for unlinked refunds. For more information, see [Process an Unlinked Refund](https://developer.squareup.com/docs/refunds-api/unlinked-refunds). For refunds linked to Square payments, `destination_id` is usually omitted; in this case, funds will be returned to the original payment source. The field may be specified in order to request a cross-method refund to a gift card. For more information, see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards)., unlinked: bool # Indicates that the refund is not linked to a Square payment. If set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not be provided., location_id: str # The location ID associated with the unlinked refund. Required for requests specifying `unlinked=true`. Otherwise, if included when `unlinked=false`, will throw an error., customer_id: str # The [Customer](entity:Customer) ID of the customer associated with the refund. This is required if the `destination_id` refers to a card on file created using the Cards API. Only allowed when `unlinked=true`., reason: str # A description of the reason for the refund., payment_version_token: str # Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned. If the versions match, or the field is not provided, the refund proceeds as normal., team_member_id: str # An optional [TeamMember](entity:TeamMember) ID to associate with this refund., cash_details: map{seller_supplied_money!: map, change_back_money: map} # Stores details about a cash refund. Contains only non-confidential information., external_details: map{type!: str, source!: str, source_id: str} # Stores details about an external refund. Contains only non-confidential information.} @returns(200) {errors: [map], refund: map{id: str, status: str?, location_id: str?, unlinked: bool, destination_type: str?, destination_details: map{card_details: map{card: map, entry_method: str?, auth_result_code: str?}, cash_details: map{seller_supplied_money: map, change_back_money: map}, external_details: map{type: str, source: str, source_id: str?}}, amount_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, processing_fee: [map]?, payment_id: str?, order_id: str?, reason: str?, created_at: str, updated_at: str, team_member_id: str, terminal_refund_id: str}} # Success @endpoint GET /v2/refunds/{refund_id} @desc GetPaymentRefund @required {refund_id: str # The unique ID for the desired `PaymentRefund`.} @returns(200) {errors: [map], refund: map{id: str, status: str?, location_id: str?, unlinked: bool, destination_type: str?, destination_details: map{card_details: map{card: map, entry_method: str?, auth_result_code: str?}, cash_details: map{seller_supplied_money: map, change_back_money: map}, external_details: map{type: str, source: str, source_id: str?}}, amount_money: map{amount: int(int64)?, currency: str}, app_fee_money: map{amount: int(int64)?, currency: str}, processing_fee: [map]?, payment_id: str?, order_id: str?, reason: str?, created_at: str, updated_at: str, team_member_id: str, terminal_refund_id: str}} # Success @endgroup @group sites @endpoint GET /v2/sites @desc ListSites @returns(200) {errors: [map], sites: [map]} # Success @endpoint DELETE /v2/sites/{site_id}/snippet @desc DeleteSnippet @required {site_id: str # The ID of the site that contains the snippet.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/sites/{site_id}/snippet @desc RetrieveSnippet @required {site_id: str # The ID of the site that contains the snippet.} @returns(200) {errors: [map], snippet: map{id: str, site_id: str, content: str, created_at: str, updated_at: str}} # Success @endpoint POST /v2/sites/{site_id}/snippet @desc UpsertSnippet @required {site_id: str # The ID of the site where you want to add or update the snippet., snippet: map{id: str, site_id: str, content!: str, created_at: str, updated_at: str} # Represents the snippet that is added to a Square Online site. The snippet code is injected into the `head` element of all pages on the site, except for checkout pages.} @returns(200) {errors: [map], snippet: map{id: str, site_id: str, content: str, created_at: str, updated_at: str}} # Success @endgroup @group subscriptions @endpoint POST /v2/subscriptions @desc CreateSubscription @required {location_id: str # The ID of the location the subscription is associated with., customer_id: str # The ID of the [customer](entity:Customer) subscribing to the subscription plan variation.} @optional {idempotency_key: str # A unique string that identifies this `CreateSubscription` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)., plan_variation_id: str # The ID of the [subscription plan variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations) created using the Catalog API., start_date: str # The `YYYY-MM-DD`-formatted date to start the subscription. If it is unspecified, the subscription starts immediately., canceled_date: str # The `YYYY-MM-DD`-formatted date when the newly created subscription is scheduled for cancellation. This date overrides the cancellation date set in the plan variation configuration. If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle. When the subscription plan of the newly created subscription has a fixed number of cycles and the `canceled_date` occurs before the subscription plan completes, the specified `canceled_date` sets the date when the subscription stops through the end of the last cycle., tax_percentage: str # The tax to add when billing the subscription. The percentage is expressed in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. For example, a value of 7.5 corresponds to 7.5%., price_override_money: map{amount: int(int64), currency: str} # Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information., card_id: str # The ID of the [subscriber's](entity:Customer) [card](entity:Card) to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription., timezone: str # The timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to "America/New_York". Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)., source: map{name: str} # The origination details of the subscription., monthly_billing_anchor_date: int # The day-of-the-month to change the billing date to., phases: [map{uid: str, ordinal: int(int64), order_template_id: str, plan_phase_uid: str}] # array of phases for this subscription} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}} # Success @endpoint POST /v2/subscriptions/bulk-swap-plan @desc BulkSwapPlan @required {new_plan_variation_id: str # The ID of the new subscription plan variation. This field is required., old_plan_variation_id: str # The ID of the plan variation whose subscriptions should be swapped. Active subscriptions using this plan variation will be subscribed to the new plan variation on their next billing day., location_id: str # The ID of the location to associate with the swapped subscriptions.} @returns(200) {errors: [map], affected_subscriptions: int} # Success @endpoint POST /v2/subscriptions/search @desc SearchSubscriptions @optional {cursor: str # When the total number of resulting subscriptions exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The upper limit on the number of subscriptions to return in a paged response., query: map{filter: map} # Represents a query, consisting of specified query expressions, used to search for subscriptions., include: [str] # An option to include related information in the response. The supported values are: - `actions`: to include scheduled actions on the targeted subscriptions.} @returns(200) {errors: [map], subscriptions: [map], cursor: str} # Success @endpoint GET /v2/subscriptions/{subscription_id} @desc RetrieveSubscription @required {subscription_id: str # The ID of the subscription to retrieve.} @optional {include: str # A query parameter to specify related information to be included in the response. The supported query parameter values are: - `actions`: to include scheduled actions on the targeted subscription.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}} # Success @endpoint PUT /v2/subscriptions/{subscription_id} @desc UpdateSubscription @required {subscription_id: str # The ID of the subscription to update.} @optional {subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str, charged_through_date: str, status: str, tax_percentage: str, invoice_ids: [str], price_override_money: map, version: int(int64), created_at: str, card_id: str, timezone: str, source: map, actions: [map], monthly_billing_anchor_date: int, phases: [map], completed_date: str} # Represents a subscription purchased by a customer. For more information, see [Manage Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions).} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}} # Success @endpoint DELETE /v2/subscriptions/{subscription_id}/actions/{action_id} @desc DeleteSubscriptionAction @required {subscription_id: str # The ID of the subscription the targeted action is to act upon., action_id: str # The ID of the targeted action to be deleted.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}} # Success @endpoint POST /v2/subscriptions/{subscription_id}/billing-anchor @desc ChangeBillingAnchorDate @required {subscription_id: str # The ID of the subscription to update the billing anchor date.} @optional {monthly_billing_anchor_date: int # The anchor day for the billing cycle., effective_date: str # The `YYYY-MM-DD`-formatted date when the scheduled `BILLING_ANCHOR_CHANGE` action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the billing anchor date is changed immediately.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}, actions: [map]} # Success @endpoint POST /v2/subscriptions/{subscription_id}/cancel @desc CancelSubscription @required {subscription_id: str # The ID of the subscription to cancel.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}, actions: [map]} # Success @endpoint GET /v2/subscriptions/{subscription_id}/events @desc ListSubscriptionEvents @required {subscription_id: str # The ID of the subscription to retrieve the events for.} @optional {cursor: str # When the total number of resulting subscription events exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., limit: int # The upper limit on the number of subscription events to return in a paged response.} @returns(200) {errors: [map], subscription_events: [map], cursor: str} # Success @endpoint POST /v2/subscriptions/{subscription_id}/pause @desc PauseSubscription @required {subscription_id: str # The ID of the subscription to pause.} @optional {pause_effective_date: str # The `YYYY-MM-DD`-formatted date when the scheduled `PAUSE` action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the subscription is paused on the starting date of the next billing cycle., pause_cycle_duration: int(int64) # The number of billing cycles the subscription will be paused before it is reactivated. When this is set, a `RESUME` action is also scheduled to take place on the subscription at the end of the specified pause cycle duration. In this case, neither `resume_effective_date` nor `resume_change_timing` may be specified., resume_effective_date: str # The date when the subscription is reactivated by a scheduled `RESUME` action. This date must be at least one billing cycle ahead of `pause_effective_date`., resume_change_timing: str(IMMEDIATE/END_OF_BILLING_CYCLE) # Supported timings when a pending change, as an action, takes place to a subscription., pause_reason: str # The user-provided reason to pause the subscription.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}, actions: [map]} # Success @endpoint POST /v2/subscriptions/{subscription_id}/resume @desc ResumeSubscription @required {subscription_id: str # The ID of the subscription to resume.} @optional {resume_effective_date: str # The `YYYY-MM-DD`-formatted date when the subscription reactivated., resume_change_timing: str(IMMEDIATE/END_OF_BILLING_CYCLE) # Supported timings when a pending change, as an action, takes place to a subscription.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}, actions: [map]} # Success @endpoint POST /v2/subscriptions/{subscription_id}/swap-plan @desc SwapPlan @required {subscription_id: str # The ID of the subscription to swap the subscription plan for.} @optional {new_plan_variation_id: str # The ID of the new subscription plan variation. This field is required., phases: [map{ordinal!: int(int64), order_template_id: str}] # A list of PhaseInputs, to pass phase-specific information used in the swap.} @returns(200) {errors: [map], subscription: map{id: str, location_id: str, plan_variation_id: str, customer_id: str, start_date: str, canceled_date: str?, charged_through_date: str, status: str, tax_percentage: str?, invoice_ids: [str], price_override_money: map{amount: int(int64)?, currency: str}, version: int(int64), created_at: str, card_id: str?, timezone: str, source: map{name: str?}, actions: [map]?, monthly_billing_anchor_date: int, phases: [map], completed_date: str?}, actions: [map]} # Success @endgroup @group team-members @endpoint POST /v2/team-members @desc CreateTeamMember @optional {idempotency_key: str # A unique string that identifies this `CreateTeamMember` request. Keys can be any valid string, but must be unique for every request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). The minimum length is 1 and the maximum length is 45., team_member: map{id: str, reference_id: str, is_owner: bool, status: str, given_name: str, family_name: str, email_address: str, phone_number: str, created_at: str, updated_at: str, assigned_locations: map, wage_setting: map} # A record representing an individual team member for a business.} @returns(200) {team_member: map{id: str, reference_id: str?, is_owner: bool, status: str, given_name: str?, family_name: str?, email_address: str?, phone_number: str?, created_at: str, updated_at: str, assigned_locations: map{assignment_type: str, location_ids: [str]?}, wage_setting: map{team_member_id: str?, job_assignments: [map]?, is_overtime_exempt: bool?, version: int, created_at: str, updated_at: str}}, errors: [map]} # Success @endpoint POST /v2/team-members/bulk-create @desc BulkCreateTeamMembers @required {team_members: map # The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`. The maximum number of create objects is 25. If you include a team member's `wage_setting`, you must provide `job_id` for each job assignment. To get job IDs, call [ListJobs](api-endpoint:Team-ListJobs).} @returns(200) {team_members: map, errors: [map]} # Success @endpoint POST /v2/team-members/bulk-update @desc BulkUpdateTeamMembers @required {team_members: map # The data used to update the `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`. The maximum number of update objects is 25. For each team member, include the fields to add, change, or clear. Fields can be cleared using a null value. To update `wage_setting.job_assignments`, you must provide the complete list of job assignments. If needed, call [ListJobs](api-endpoint:Team-ListJobs) to get the required `job_id` values.} @returns(200) {team_members: map, errors: [map]} # Success @endpoint GET /v2/team-members/jobs @desc ListJobs @optional {cursor: str # The pagination cursor returned by the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).} @returns(200) {jobs: [map], cursor: str, errors: [map]} # Success @endpoint POST /v2/team-members/jobs @desc CreateJob @required {job: map{id: str, title: str, is_tip_eligible: bool, created_at: str, updated_at: str, version: int} # Represents a job that can be assigned to [team members](entity:TeamMember). This object defines the job's title and tip eligibility. Compensation is defined in a [job assignment](entity:JobAssignment) in a team member's wage setting., idempotency_key: str # A unique identifier for the `CreateJob` request. Keys can be any valid string, but must be unique for each request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).} @returns(200) {job: map{id: str, title: str?, is_tip_eligible: bool?, created_at: str, updated_at: str, version: int}, errors: [map]} # Success @endpoint GET /v2/team-members/jobs/{job_id} @desc RetrieveJob @required {job_id: str # The ID of the job to retrieve.} @returns(200) {job: map{id: str, title: str?, is_tip_eligible: bool?, created_at: str, updated_at: str, version: int}, errors: [map]} # Success @endpoint PUT /v2/team-members/jobs/{job_id} @desc UpdateJob @required {job_id: str # The ID of the job to update., job: map{id: str, title: str, is_tip_eligible: bool, created_at: str, updated_at: str, version: int} # Represents a job that can be assigned to [team members](entity:TeamMember). This object defines the job's title and tip eligibility. Compensation is defined in a [job assignment](entity:JobAssignment) in a team member's wage setting.} @returns(200) {job: map{id: str, title: str?, is_tip_eligible: bool?, created_at: str, updated_at: str, version: int}, errors: [map]} # Success @endpoint POST /v2/team-members/search @desc SearchTeamMembers @optional {query: map{filter: map} # Represents the parameters in a search for `TeamMember` objects., limit: int # The maximum number of `TeamMember` objects in a page (100 by default)., cursor: str # The opaque cursor for fetching the next page. For more information, see [pagination](https://developer.squareup.com/docs/working-with-apis/pagination).} @returns(200) {team_members: [map], cursor: str, errors: [map]} # Success @endpoint GET /v2/team-members/{team_member_id} @desc RetrieveTeamMember @required {team_member_id: str # The ID of the team member to retrieve.} @returns(200) {team_member: map{id: str, reference_id: str?, is_owner: bool, status: str, given_name: str?, family_name: str?, email_address: str?, phone_number: str?, created_at: str, updated_at: str, assigned_locations: map{assignment_type: str, location_ids: [str]?}, wage_setting: map{team_member_id: str?, job_assignments: [map]?, is_overtime_exempt: bool?, version: int, created_at: str, updated_at: str}}, errors: [map]} # Success @endpoint PUT /v2/team-members/{team_member_id} @desc UpdateTeamMember @required {team_member_id: str # The ID of the team member to update.} @optional {team_member: map{id: str, reference_id: str, is_owner: bool, status: str, given_name: str, family_name: str, email_address: str, phone_number: str, created_at: str, updated_at: str, assigned_locations: map, wage_setting: map} # A record representing an individual team member for a business.} @returns(200) {team_member: map{id: str, reference_id: str?, is_owner: bool, status: str, given_name: str?, family_name: str?, email_address: str?, phone_number: str?, created_at: str, updated_at: str, assigned_locations: map{assignment_type: str, location_ids: [str]?}, wage_setting: map{team_member_id: str?, job_assignments: [map]?, is_overtime_exempt: bool?, version: int, created_at: str, updated_at: str}}, errors: [map]} # Success @endpoint GET /v2/team-members/{team_member_id}/wage-setting @desc RetrieveWageSetting @required {team_member_id: str # The ID of the team member for which to retrieve the wage setting.} @returns(200) {wage_setting: map{team_member_id: str?, job_assignments: [map]?, is_overtime_exempt: bool?, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endpoint PUT /v2/team-members/{team_member_id}/wage-setting @desc UpdateWageSetting @required {team_member_id: str # The ID of the team member for which to update the `WageSetting` object., wage_setting: map{team_member_id: str, job_assignments: [map], is_overtime_exempt: bool, version: int, created_at: str, updated_at: str} # Represents information about the overtime exemption status, job assignments, and compensation for a [team member](entity:TeamMember).} @returns(200) {wage_setting: map{team_member_id: str?, job_assignments: [map]?, is_overtime_exempt: bool?, version: int, created_at: str, updated_at: str}, errors: [map]} # Success @endgroup @group terminals @endpoint POST /v2/terminals/actions @desc CreateTerminalAction @required {idempotency_key: str # A unique string that identifies this `CreateAction` request. Keys can be any valid string but must be unique for every `CreateAction` request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., action: map{id: str, device_id: str, deadline_duration: str, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str, type: str, qr_code_options: map, save_card_options: map, signature_options: map, confirmation_options: map, receipt_options: map, data_collection_options: map, select_options: map, device_metadata: map, await_next_action: bool, await_next_action_duration: str} # Represents an action processed by the Square Terminal.} @returns(200) {errors: [map], action: map{id: str, device_id: str?, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str, type: str, qr_code_options: map{title: str, body: str, barcode_contents: str}, save_card_options: map{customer_id: str, card_id: str, reference_id: str?}, signature_options: map{title: str, body: str, signature: [map]}, confirmation_options: map{title: str, body: str, agree_button_text: str, disagree_button_text: str?, decision: map{has_agreed: bool}}, receipt_options: map{payment_id: str, print_only: bool?, is_duplicate: bool?}, data_collection_options: map{title: str, body: str, input_type: str, collected_data: map{input_text: str}}, select_options: map{title: str, body: str, options: [map], selected_option: map{reference_id: str, title: str}}, device_metadata: map{battery_percentage: str?, charging_state: str?, location_id: str?, merchant_id: str?, network_connection_type: str?, payment_region: str?, serial_number: str?, os_version: str?, app_version: str?, wifi_network_name: str?, wifi_network_strength: str?, ip_address: str?}, await_next_action: bool?, await_next_action_duration: str?}} # Success @endpoint POST /v2/terminals/actions/search @desc SearchTerminalActions @optional {query: map{filter: map, sort: map}, cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., limit: int # Limit the number of results returned for a single request.} @returns(200) {errors: [map], action: [map], cursor: str} # Success @endpoint GET /v2/terminals/actions/{action_id} @desc GetTerminalAction @required {action_id: str # Unique ID for the desired `TerminalAction`.} @returns(200) {errors: [map], action: map{id: str, device_id: str?, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str, type: str, qr_code_options: map{title: str, body: str, barcode_contents: str}, save_card_options: map{customer_id: str, card_id: str, reference_id: str?}, signature_options: map{title: str, body: str, signature: [map]}, confirmation_options: map{title: str, body: str, agree_button_text: str, disagree_button_text: str?, decision: map{has_agreed: bool}}, receipt_options: map{payment_id: str, print_only: bool?, is_duplicate: bool?}, data_collection_options: map{title: str, body: str, input_type: str, collected_data: map{input_text: str}}, select_options: map{title: str, body: str, options: [map], selected_option: map{reference_id: str, title: str}}, device_metadata: map{battery_percentage: str?, charging_state: str?, location_id: str?, merchant_id: str?, network_connection_type: str?, payment_region: str?, serial_number: str?, os_version: str?, app_version: str?, wifi_network_name: str?, wifi_network_strength: str?, ip_address: str?}, await_next_action: bool?, await_next_action_duration: str?}} # Success @endpoint POST /v2/terminals/actions/{action_id}/cancel @desc CancelTerminalAction @required {action_id: str # Unique ID for the desired `TerminalAction`.} @returns(200) {errors: [map], action: map{id: str, device_id: str?, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str, type: str, qr_code_options: map{title: str, body: str, barcode_contents: str}, save_card_options: map{customer_id: str, card_id: str, reference_id: str?}, signature_options: map{title: str, body: str, signature: [map]}, confirmation_options: map{title: str, body: str, agree_button_text: str, disagree_button_text: str?, decision: map{has_agreed: bool}}, receipt_options: map{payment_id: str, print_only: bool?, is_duplicate: bool?}, data_collection_options: map{title: str, body: str, input_type: str, collected_data: map{input_text: str}}, select_options: map{title: str, body: str, options: [map], selected_option: map{reference_id: str, title: str}}, device_metadata: map{battery_percentage: str?, charging_state: str?, location_id: str?, merchant_id: str?, network_connection_type: str?, payment_region: str?, serial_number: str?, os_version: str?, app_version: str?, wifi_network_name: str?, wifi_network_strength: str?, ip_address: str?}, await_next_action: bool?, await_next_action_duration: str?}} # Success @endpoint POST /v2/terminals/actions/{action_id}/dismiss @desc DismissTerminalAction @required {action_id: str # Unique ID for the `TerminalAction` associated with the action to be dismissed.} @returns(200) {errors: [map], action: map{id: str, device_id: str?, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str, type: str, qr_code_options: map{title: str, body: str, barcode_contents: str}, save_card_options: map{customer_id: str, card_id: str, reference_id: str?}, signature_options: map{title: str, body: str, signature: [map]}, confirmation_options: map{title: str, body: str, agree_button_text: str, disagree_button_text: str?, decision: map{has_agreed: bool}}, receipt_options: map{payment_id: str, print_only: bool?, is_duplicate: bool?}, data_collection_options: map{title: str, body: str, input_type: str, collected_data: map{input_text: str}}, select_options: map{title: str, body: str, options: [map], selected_option: map{reference_id: str, title: str}}, device_metadata: map{battery_percentage: str?, charging_state: str?, location_id: str?, merchant_id: str?, network_connection_type: str?, payment_region: str?, serial_number: str?, os_version: str?, app_version: str?, wifi_network_name: str?, wifi_network_strength: str?, ip_address: str?}, await_next_action: bool?, await_next_action_duration: str?}} # Success @endpoint POST /v2/terminals/checkouts @desc CreateTerminalCheckout @required {idempotency_key: str # A unique string that identifies this `CreateCheckout` request. Keys can be any valid string but must be unique for every `CreateCheckout` request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information., checkout: map{id: str, amount_money!: map, reference_id: str, note: str, order_id: str, payment_options: map, device_options!: map, deadline_duration: str, status: str, cancel_reason: str, payment_ids: [str], created_at: str, updated_at: str, app_id: str, location_id: str, payment_type: str, team_member_id: str, customer_id: str, app_fee_money: map, statement_description_identifier: str, tip_money: map} # Represents a checkout processed by the Square Terminal.} @returns(200) {errors: [map], checkout: map{id: str, amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, note: str?, order_id: str?, payment_options: map{autocomplete: bool?, delay_duration: str?, accept_partial_authorization: bool?, delay_action: str}, device_options: map{device_id: str, skip_receipt_screen: bool?, collect_signature: bool?, tip_settings: map{allow_tipping: bool?, separate_tip_screen: bool?, custom_tip_field: bool?, tip_percentages: [int]?, smart_tipping: bool?}, show_itemized_cart: bool?}, deadline_duration: str?, status: str, cancel_reason: str, payment_ids: [str], created_at: str, updated_at: str, app_id: str, location_id: str, payment_type: str, team_member_id: str?, customer_id: str?, app_fee_money: map{amount: int(int64)?, currency: str}, statement_description_identifier: str?, tip_money: map{amount: int(int64)?, currency: str}}} # Success @endpoint POST /v2/terminals/checkouts/search @desc SearchTerminalCheckouts @optional {query: map{filter: map, sort: map}, cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information., limit: int # Limits the number of results returned for a single request.} @returns(200) {errors: [map], checkouts: [map], cursor: str} # Success @endpoint GET /v2/terminals/checkouts/{checkout_id} @desc GetTerminalCheckout @required {checkout_id: str # The unique ID for the desired `TerminalCheckout`.} @returns(200) {errors: [map], checkout: map{id: str, amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, note: str?, order_id: str?, payment_options: map{autocomplete: bool?, delay_duration: str?, accept_partial_authorization: bool?, delay_action: str}, device_options: map{device_id: str, skip_receipt_screen: bool?, collect_signature: bool?, tip_settings: map{allow_tipping: bool?, separate_tip_screen: bool?, custom_tip_field: bool?, tip_percentages: [int]?, smart_tipping: bool?}, show_itemized_cart: bool?}, deadline_duration: str?, status: str, cancel_reason: str, payment_ids: [str], created_at: str, updated_at: str, app_id: str, location_id: str, payment_type: str, team_member_id: str?, customer_id: str?, app_fee_money: map{amount: int(int64)?, currency: str}, statement_description_identifier: str?, tip_money: map{amount: int(int64)?, currency: str}}} # Success @endpoint POST /v2/terminals/checkouts/{checkout_id}/cancel @desc CancelTerminalCheckout @required {checkout_id: str # The unique ID for the desired `TerminalCheckout`.} @returns(200) {errors: [map], checkout: map{id: str, amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, note: str?, order_id: str?, payment_options: map{autocomplete: bool?, delay_duration: str?, accept_partial_authorization: bool?, delay_action: str}, device_options: map{device_id: str, skip_receipt_screen: bool?, collect_signature: bool?, tip_settings: map{allow_tipping: bool?, separate_tip_screen: bool?, custom_tip_field: bool?, tip_percentages: [int]?, smart_tipping: bool?}, show_itemized_cart: bool?}, deadline_duration: str?, status: str, cancel_reason: str, payment_ids: [str], created_at: str, updated_at: str, app_id: str, location_id: str, payment_type: str, team_member_id: str?, customer_id: str?, app_fee_money: map{amount: int(int64)?, currency: str}, statement_description_identifier: str?, tip_money: map{amount: int(int64)?, currency: str}}} # Success @endpoint POST /v2/terminals/checkouts/{checkout_id}/dismiss @desc DismissTerminalCheckout @required {checkout_id: str # Unique ID for the `TerminalCheckout` associated with the checkout to be dismissed.} @returns(200) {errors: [map], checkout: map{id: str, amount_money: map{amount: int(int64)?, currency: str}, reference_id: str?, note: str?, order_id: str?, payment_options: map{autocomplete: bool?, delay_duration: str?, accept_partial_authorization: bool?, delay_action: str}, device_options: map{device_id: str, skip_receipt_screen: bool?, collect_signature: bool?, tip_settings: map{allow_tipping: bool?, separate_tip_screen: bool?, custom_tip_field: bool?, tip_percentages: [int]?, smart_tipping: bool?}, show_itemized_cart: bool?}, deadline_duration: str?, status: str, cancel_reason: str, payment_ids: [str], created_at: str, updated_at: str, app_id: str, location_id: str, payment_type: str, team_member_id: str?, customer_id: str?, app_fee_money: map{amount: int(int64)?, currency: str}, statement_description_identifier: str?, tip_money: map{amount: int(int64)?, currency: str}}} # Success @endpoint POST /v2/terminals/refunds @desc CreateTerminalRefund @required {idempotency_key: str # A unique string that identifies this `CreateRefund` request. Keys can be any valid string but must be unique for every `CreateRefund` request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information.} @optional {refund: map{id: str, refund_id: str, payment_id!: str, order_id: str, amount_money!: map, reason!: str, device_id!: str, deadline_duration: str, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str} # Represents a payment refund processed by the Square Terminal. Only supports Interac (Canadian debit network) payment refunds.} @returns(200) {errors: [map], refund: map{id: str, refund_id: str, payment_id: str, order_id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, device_id: str, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str}} # Success @endpoint POST /v2/terminals/refunds/search @desc SearchTerminalRefunds @optional {query: map{filter: map, sort: map}, cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query., limit: int # Limits the number of results returned for a single request.} @returns(200) {errors: [map], refunds: [map], cursor: str} # Success @endpoint GET /v2/terminals/refunds/{terminal_refund_id} @desc GetTerminalRefund @required {terminal_refund_id: str # The unique ID for the desired `TerminalRefund`.} @returns(200) {errors: [map], refund: map{id: str, refund_id: str, payment_id: str, order_id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, device_id: str, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str}} # Success @endpoint POST /v2/terminals/refunds/{terminal_refund_id}/cancel @desc CancelTerminalRefund @required {terminal_refund_id: str # The unique ID for the desired `TerminalRefund`.} @returns(200) {errors: [map], refund: map{id: str, refund_id: str, payment_id: str, order_id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, device_id: str, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str}} # Success @endpoint POST /v2/terminals/refunds/{terminal_refund_id}/dismiss @desc DismissTerminalRefund @required {terminal_refund_id: str # Unique ID for the `TerminalRefund` associated with the refund to be dismissed.} @returns(200) {errors: [map], refund: map{id: str, refund_id: str, payment_id: str, order_id: str, amount_money: map{amount: int(int64)?, currency: str}, reason: str, device_id: str, deadline_duration: str?, status: str, cancel_reason: str, created_at: str, updated_at: str, app_id: str, location_id: str}} # Success @endgroup @group transfer-orders @endpoint POST /v2/transfer-orders @desc CreateTransferOrder @required {idempotency_key: str # A unique string that identifies this CreateTransferOrder request. Keys can be any valid string but must be unique for every CreateTransferOrder request., transfer_order: map{source_location_id!: str, destination_location_id!: str, expected_at: str, notes: str, tracking_number: str, created_by_team_member_id: str, line_items: [map]} # Data for creating a new transfer order to move [CatalogItemVariation](entity:CatalogItemVariation)s between [Location](entity:Location)s. Used with the [CreateTransferOrder](api-endpoint:TransferOrders-CreateTransferOrder) endpoint.} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endpoint POST /v2/transfer-orders/search @desc SearchTransferOrders @optional {query: map{filter: map, sort: map} # Query parameters for searching transfer orders, cursor: str # Pagination cursor from a previous search response, limit: int # Maximum number of results to return (1-100)} @returns(200) {transfer_orders: [map], cursor: str, errors: [map]} # Success @endpoint DELETE /v2/transfer-orders/{transfer_order_id} @desc DeleteTransferOrder @required {transfer_order_id: str # The ID of the transfer order to delete} @optional {version: int(int64) # Version for optimistic concurrency} @returns(200) {errors: [map]} # Success @endpoint GET /v2/transfer-orders/{transfer_order_id} @desc RetrieveTransferOrder @required {transfer_order_id: str # The ID of the transfer order to retrieve} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endpoint PUT /v2/transfer-orders/{transfer_order_id} @desc UpdateTransferOrder @required {transfer_order_id: str # The ID of the transfer order to update, idempotency_key: str # A unique string that identifies this UpdateTransferOrder request. Keys must contain only alphanumeric characters, dashes and underscores, transfer_order: map{source_location_id: str, destination_location_id: str, expected_at: str, notes: str, tracking_number: str, line_items: [map]} # Data model for updating a transfer order. All fields are optional.} @optional {version: int(int64) # Version for optimistic concurrency} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endpoint POST /v2/transfer-orders/{transfer_order_id}/cancel @desc CancelTransferOrder @required {transfer_order_id: str # The ID of the transfer order to cancel. Must be in STARTED or PARTIALLY_RECEIVED status., idempotency_key: str # A unique string that identifies this UpdateTransferOrder request. Keys can be any valid string but must be unique for every UpdateTransferOrder request.} @optional {version: int(int64) # Version for optimistic concurrency} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endpoint POST /v2/transfer-orders/{transfer_order_id}/receive @desc ReceiveTransferOrder @required {transfer_order_id: str # The ID of the transfer order to receive items for, idempotency_key: str # A unique key to make this request idempotent, receipt: map{line_items: [map]} # The goods receipt details for a transfer order. This object represents a single receipt of goods against a transfer order, tracking: - Which [CatalogItemVariation](entity:CatalogItemVariation)s were received - Quantities received in good condition - Quantities damaged during transit/handling - Quantities canceled during receipt Multiple goods receipts can be created for a single transfer order to handle: - Partial deliveries - Multiple shipments - Split receipts across different dates - Cancellations of specific quantities Each receipt automatically: - Updates the transfer order status - Adjusts received quantities - Updates inventory levels at both source and destination [Location](entity:Location)s} @optional {version: int(int64) # Version for optimistic concurrency} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endpoint POST /v2/transfer-orders/{transfer_order_id}/start @desc StartTransferOrder @required {transfer_order_id: str # The ID of the transfer order to start. Must be in DRAFT status., idempotency_key: str # A unique string that identifies this UpdateTransferOrder request. Keys can be any valid string but must be unique for every UpdateTransferOrder request.} @optional {version: int(int64) # Version for optimistic concurrency} @returns(200) {transfer_order: map{id: str, source_location_id: str?, destination_location_id: str?, status: str, created_at: str, updated_at: str, expected_at: str?, completed_at: str, notes: str?, tracking_number: str?, created_by_team_member_id: str, line_items: [map]?, version: int(int64)}, errors: [map]} # Success @endgroup @group vendors @endpoint POST /v2/vendors/bulk-create @desc BulkCreateVendors @required {vendors: map # Specifies a set of new [Vendor](entity:Vendor) objects as represented by a collection of idempotency-key/`Vendor`-object pairs.} @returns(200) {errors: [map], responses: map} # Success @endpoint POST /v2/vendors/bulk-retrieve @desc BulkRetrieveVendors @optional {vendor_ids: [str] # IDs of the [Vendor](entity:Vendor) objects to retrieve.} @returns(200) {errors: [map], responses: map} # Success @endpoint PUT /v2/vendors/bulk-update @desc BulkUpdateVendors @required {vendors: map # A set of [UpdateVendorRequest](entity:UpdateVendorRequest) objects encapsulating to-be-updated [Vendor](entity:Vendor) objects. The set is represented by a collection of `Vendor`-ID/`UpdateVendorRequest`-object pairs.} @returns(200) {errors: [map], responses: map} # Success @endpoint POST /v2/vendors/create @desc CreateVendor @required {idempotency_key: str # A client-supplied, universally unique identifier (UUID) to make this [CreateVendor](api-endpoint:Vendors-CreateVendor) call idempotent. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information.} @optional {vendor: map{id: str, created_at: str, updated_at: str, name: str, address: map, contacts: [map], account_number: str, note: str, version: int, status: str} # Represents a supplier to a seller.} @returns(200) {errors: [map], vendor: map{id: str, created_at: str, updated_at: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, contacts: [map]?, account_number: str?, note: str?, version: int, status: str}} # Success @endpoint POST /v2/vendors/search @desc SearchVendors @optional {filter: map{name: [str], status: [str]} # Defines supported query expressions to search for vendors by., sort: map{field: str, order: str} # Defines a sorter used to sort results from [SearchVendors](api-endpoint:Vendors-SearchVendors)., cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.} @returns(200) {errors: [map], vendors: [map], cursor: str} # Success @endpoint GET /v2/vendors/{vendor_id} @desc RetrieveVendor @required {vendor_id: str # ID of the [Vendor](entity:Vendor) to retrieve.} @returns(200) {errors: [map], vendor: map{id: str, created_at: str, updated_at: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, contacts: [map]?, account_number: str?, note: str?, version: int, status: str}} # Success @endpoint PUT /v2/vendors/{vendor_id} @desc UpdateVendor @required {vendor: map{id: str, created_at: str, updated_at: str, name: str, address: map, contacts: [map], account_number: str, note: str, version: int, status: str} # Represents a supplier to a seller.} @optional {idempotency_key: str # A client-supplied, universally unique identifier (UUID) for the request. See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the [API Development 101](https://developer.squareup.com/docs/buildbasics) section for more information.} @returns(200) {errors: [map], vendor: map{id: str, created_at: str, updated_at: str, name: str?, address: map{address_line_1: str?, address_line_2: str?, address_line_3: str?, locality: str?, sublocality: str?, sublocality_2: str?, sublocality_3: str?, administrative_district_level_1: str?, administrative_district_level_2: str?, administrative_district_level_3: str?, postal_code: str?, country: str, first_name: str?, last_name: str?}, contacts: [map]?, account_number: str?, note: str?, version: int, status: str}} # Success @endgroup @group webhooks @endpoint GET /v2/webhooks/event-types @desc ListWebhookEventTypes @optional {api_version: str # The API version for which to list event types. Setting this field overrides the default version used by the application.} @returns(200) {errors: [map], event_types: [str], metadata: [map]} # Success @endpoint GET /v2/webhooks/subscriptions @desc ListWebhookSubscriptions @optional {cursor: str # A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)., include_disabled: bool=false # Includes disabled [Subscription](entity:WebhookSubscription)s. By default, all enabled [Subscription](entity:WebhookSubscription)s are returned., sort_order: str # Sorts the returned list by when the [Subscription](entity:WebhookSubscription) was created with the specified order. This field defaults to ASC., limit: int # The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. Default: 100} @returns(200) {errors: [map], subscriptions: [map], cursor: str} # Success @endpoint POST /v2/webhooks/subscriptions @desc CreateWebhookSubscription @required {subscription: map{id: str, name: str, enabled: bool, event_types: [str], notification_url: str, api_version: str, signature_key: str, created_at: str, updated_at: str} # Represents the details of a webhook subscription, including notification URL, event types, and signature key.} @optional {idempotency_key: str # A unique string that identifies the [CreateWebhookSubscription](api-endpoint:WebhookSubscriptions-CreateWebhookSubscription) request.} @returns(200) {errors: [map], subscription: map{id: str, name: str?, enabled: bool?, event_types: [str]?, notification_url: str?, api_version: str?, signature_key: str, created_at: str, updated_at: str}} # Success @endpoint DELETE /v2/webhooks/subscriptions/{subscription_id} @desc DeleteWebhookSubscription @required {subscription_id: str # [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to delete.} @returns(200) {errors: [map]} # Success @endpoint GET /v2/webhooks/subscriptions/{subscription_id} @desc RetrieveWebhookSubscription @required {subscription_id: str # [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to retrieve.} @returns(200) {errors: [map], subscription: map{id: str, name: str?, enabled: bool?, event_types: [str]?, notification_url: str?, api_version: str?, signature_key: str, created_at: str, updated_at: str}} # Success @endpoint PUT /v2/webhooks/subscriptions/{subscription_id} @desc UpdateWebhookSubscription @required {subscription_id: str # [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update.} @optional {subscription: map{id: str, name: str, enabled: bool, event_types: [str], notification_url: str, api_version: str, signature_key: str, created_at: str, updated_at: str} # Represents the details of a webhook subscription, including notification URL, event types, and signature key.} @returns(200) {errors: [map], subscription: map{id: str, name: str?, enabled: bool?, event_types: [str]?, notification_url: str?, api_version: str?, signature_key: str, created_at: str, updated_at: str}} # Success @endpoint POST /v2/webhooks/subscriptions/{subscription_id}/signature-key @desc UpdateWebhookSubscriptionSignatureKey @required {subscription_id: str # [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update.} @optional {idempotency_key: str # A unique string that identifies the [UpdateWebhookSubscriptionSignatureKey](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscriptionSignatureKey) request.} @returns(200) {errors: [map], signature_key: str} # Success @endpoint POST /v2/webhooks/subscriptions/{subscription_id}/test @desc TestWebhookSubscription @required {subscription_id: str # [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to test.} @optional {event_type: str # The event type that will be used to test the [Subscription](entity:WebhookSubscription). The event type must be contained in the list of event types in the [Subscription](entity:WebhookSubscription).} @returns(200) {errors: [map], subscription_test_result: map{id: str, status_code: int?, payload: str?, created_at: str, updated_at: str}} # Success @endgroup @end