Cambiar el estado de facturación de la suscripción de un usuarioChange the billing state of a subscription for a user

Usa este método en la API de compra de Microsoft Store para cambiar el estado de facturación del complemento de una suscripción de un usuario.Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. Puedes cancelar, ampliar, reembolsar o deshabilitar la renovación automática de una suscripción.You can cancel, extend, refund, or disable automatic renewal for a subscription.

Nota

Este método solo puede usarse en cuentas de desarrollador aprovisionadas por Microsoft para que puedan crear complementos de una suscripción para aplicaciones para la Plataforma universal de Windows (UWP).This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. Actualmente, los complementos de una suscripción no están disponibles para la mayoría de las cuentas de desarrollador.Subscription add-ons are currently not available to most developer accounts.

Requisitos previosPrerequisites

Para usar este método, necesitarás:To use this method, you will need:

  • Un token de acceso de Azure AD que tiene el valor de URI de audiencia https://onestore.microsoft.com.An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • Una clave de id. de Microsoft Store que representa la identidad del usuario que tiene un derecho a la suscripción que quieres cambiar.A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

Para obtener más información, consulta Administrar los derechos de producto de un servicio.For more information, see Manage product entitlements from a service.

SolicitudRequest

Sintaxis de la solicitudRequest syntax

MétodoMethod URI de la solicitudRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

Encabezado de la solicitudRequest header

EncabezadoHeader TipoType DescripciónDescription
AutorizaciónAuthorization stringstring Obligatorio.Required. El token de acceso de Azure AD en el formulario portador < token>.The Azure AD access token in the form Bearer <token>.
HostHost stringstring Debe establecerse en el valor purchase.mp.microsoft.com.Must be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length númeronumber Longitud del cuerpo de la solicitud.The length of the request body.
Content-TypeContent-Type stringstring Especifica los tipos de solicitud y respuesta.Specifies the request and response type. Actualmente, el único valor admitido es application/json.Currently, the only supported value is application/json.

Parámetros de solicitudRequest parameters

NombreName TipoType DescripciónDescription RequeridoRequired
recurrenceIdrecurrenceId stringstring El identificador de la suscripción que quieres cambiar.The ID of the subscription you want to change. Para obtener este identificador, llame a la obtener las suscripciones para un usuario método, identificar la entrada de cuerpo de respuesta que representa el complemento de suscripción que desee cambiar y utilice el valor de la id campo para la entrada.To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. Yes

Cuerpo de la solicitudRequest body

CampoField TipoType DescripciónDescription RequeridoRequired
b2bKeyb2bKey stringstring La clave de id. de Microsoft Store que representa la identidad del usuario cuya suscripción quieres cambiar.The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. Yes
changeTypechangeType stringstring Una de las cadenas siguientes que identifica el tipo de cambio que quieres hacer:One of the following strings that identifies the type of change you want to make:
  • Cancelar: Cancela la suscripción.Cancel: Cancels the subscription.
  • Extender: Extiende la suscripción.Extend: Extends the subscription. Si especificas este valor, también debes incluir el parámetro extensionTimeInDays.If you specify this value, you must also include the extensionTimeInDays parameter.
  • Reembolsar: Reembolsos de la suscripción al cliente.Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew: Deshabilita la renovación automática para la suscripción.ToggleAutoRenew: Disables automatic renewal for the subscription. Si actualmente la renovación automática está deshabilitada para la suscripción, este valor no hace nada.If automatic renewal is currently disabled for the subscription, this value does nothing.
Yes
extensionTimeInDaysextensionTimeInDays stringstring Si el parámetro changeType tiene el valor Extend, este parámetro especifica el número de días para ampliar la suscripción.If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. Sí, si changeType tiene el valor Extend; en caso contrario, no.Yes, if changeType has the value Extend; otherwise, no.

Ejemplo de solicitudRequest example

El siguiente ejemplo muestra cómo usar este método para ampliar el período de suscripción 5 días.The following example demonstrates how to use this method to extend the subscription period by 5 days. Reemplaza el valor b2bKey por la clave de Id. de Microsoft Store que representa la identidad del usuario cuya suscripción quieres cambiar.Replace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

RespuestaResponse

Este método devuelve un cuerpo de respuesta JSON que contiene información sobre el complemento de la suscripción que se modificó, incluidos los campos que se modificaron.This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. En el siguiente ejemplo se muestra un cuerpo de respuesta para este método.The following example demonstrates a response body for this method.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Cuerpo de la respuestaResponse body

El cuerpo de la respuesta contiene los siguientes datos.The response body contains the following data.

ValorValue TipoType DescripciónDescription
autoRenewautoRenew BooleanoBoolean Indica si la suscripción está configurada para renovarse automáticamente al final del período de suscripción actual.Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary stringstring El identificador del beneficiario del derecho que está asociado con esta suscripción.The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime stringstring La fecha y la hora a las que expirará la suscripción, en formato ISO 8601.The date and time the subscription will expire, in ISO 8601 format. Este campo solo está disponible cuando la suscripción esté en determinados estados.This field is only available when the subscription is in certain states. El momento de expiración normalmente indica cuándo expira el estado actual.The expiration time usually indicates when the current state expires. Por ejemplo, para una suscripción activa, la fecha de expiración indica cuándo se producirá la próxima renovación automática.For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace stringstring La fecha y hora en que la suscripción caducará incluido el período de gracia, en formato ISO 8601.The date and time the subscription will expire including the grace period, in ISO 8601 format. Este valor indica que cuando el usuario perderá el acceso a la suscripción después de la suscripción no ha podido renovar automáticamente.This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid stringstring El identificador de la suscripción.The ID of the subscription. Usa este valor para indicar qué suscripción quieres modificar cuando llamas al método cambiar el estado de facturación de la suscripción de un usuario.Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial BooleanoBoolean Indica si la suscripción es una versión de prueba.Indicates whether the subscription is a trial.
lastModifiedlastModified stringstring La fecha y la hora de la última modificación de la suscripción, en formato ISO 8601.The date and time the subscription was last modified, in ISO 8601 format.
marketmarket stringstring El código de país (en formato de dos letras ISO 3166-1 alfa 2) en el que el usuario compró la suscripción.The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId stringstring El identificador de la Store para el producto que representa el complemento de la suscripción en el catálogo de Microsoft Store.The Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. Un ejemplo de identificador de la Store para un producto es 9NBLGGH42CFD.An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId stringstring El identificador de la Store para la SKU que representa el complemento de la suscripción en el catálogo de Microsoft Store.The Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. Un ejemplo de identificador de la Store para un SKU es 0010.An example Store ID for a SKU is 0010.
startTimestartTime stringstring La fecha y hora de inicio de la suscripción, en formato ISO 8601.The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState stringstring Uno de los siguientes valores:One of the following values:
  • None:  Indica una suscripción permanente.None:  This indicates a perpetual subscription.
  • Active:  La suscripción está activa y el usuario tiene derecho a usar los servicios.Active:  The subscription is active and the user is entitled to use the services.
  • Inactive:  La suscripción superó la fecha de expiración, y el usuario deshabilitó la opción de renovación automática de la suscripción.Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Canceled:  La suscripción se terminó a propósito antes de la fecha de expiración, con o sin reembolso.Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  La suscripción está en notificación (es decir, la suscripción está próxima a la expiración, y Microsoft está intentando adquirir fondos para renovar la suscripción).InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • Failed:  El período de notificación terminó y no se pudo renovar la suscripción después de varios intentos.Failed:  The dunning period is over and the subscription failed to renew after several attempts.

Nota:Note:

  • Inactive/Canceled/Failed son estados terminales.Inactive/Canceled/Failed are terminal states. Cuando una suscripción entra en uno de estos estados, el usuario debe comprar la suscripción para volver a activarla.When a subscription enters one of these states, the user must repurchase the subscription to activate it again. El usuario no tiene derecho a usar los servicios de estos estados.The user is not entitled to use the services in these states.
  • Cuando una suscripción está en estado Canceled, se actualizará expirationTime con la fecha y la hora de la cancelación.When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • El identificador de la suscripción seguirá siendo el mismo durante toda su vida.The ID of the subscription will remain the same during its entire lifetime. No cambiará si la opción de renovación automática está activada o desactivada.It will not change if the auto-renew option is turned on or off. Si un usuario vuelve a comprar una suscripción después de alcanzar un estado terminal, se creará un nuevo identificador de suscripción.If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • El identificador de una suscripción debe usarse para ejecutar cualquier operación en una suscripción individual.The ID of a subscription should be used to execute any operation on an individual subscription.
  • Cuando un usuario vuelve a comprar una suscripción después de cancelarla o interrumpirla, si consultas los resultados para el usuario, obtendrás dos entradas: una con el identificador de suscripción antiguo en un estado terminal y otra con el nuevo identificador de la suscripción en un estado activo.When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • Siempre resulta recomendable comprobar tanto recurrenceState como expirationTime, ya que las actualizaciones de recurrenceState potencialmente pueden retrasarse unos pocos minutos (o, en ocasiones, horas).It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate stringstring La fecha y la hora a las que se canceló la suscripción del usuario, en formato ISO 8601.The date and time the user's subscription was cancelled, in ISO 8601 format.